Why not go the other way round and also allow resources to be specified without suffix @AcmeBlog/Resources/views/Default/common/template4.html.twig?

@Tobion Are you suggesting not making the Resources/views part automatic and requiring it in the path when rendering templates (like you have done in your example)? Or do you mean something else (I was confused by the word "suffix").

If you do mean requiring Resources/views to be in the path (like in your example), I would prefer this (prefer the simplicity + consistency). But it makes the paths long, so I would challenge us to think of other clever things (or settle for Javier's proposal, which I very much like). What about:

• Recommending that views/ live at the root of the bundle directory?
• Removing the .html.twig suffix and simply using .twig

If we did these, then suddenly the explicit/long way isn't long at all:

I don't take these changes lightly (we would of course protect BC, but changes like this affect documentation, blog posts, etc), but I think we should really ask what the "best" way is (we now have years of experience using all of this). And then figure out if we can do the "best" way without breaking BC.

@weaverryan the .html.twig extension is used to guess the fromat for the autoescaping. for instance, using .js.twig would enable the autoescaping in js mode rather than html.

@weaverryan No I was suggesting to remove the bundle suffix also from other resource references.

@stof Ah, good catch. But still, we could easy and safely assume the HTML escape format when there is no format.

@Tobion we once a long time ago removed the Bundle suffix, and then instantly all hated it :). "AcmeDemo" just wasn't clear - it wasn't obvious it was a bundle anymore. But I think anything is worth discussing :).

My 10c: I think it should always be the Aggressive Proposal.

I was going to say it should be the "Easy Proposal" but then realised that resources aren't always templates... so could come from a directory other than views. The Aggressive Proposal is completely safe, no matter what resource/template/etc is being requested.

I think keeping Bundle in the bundle name is important for consistency (& less magic). I also think the template type suffix should be there as well to make it explicit and consistent.

So I think the example in the first post should be:
@ AcmeBlogBundle/views/Default/common/template4.html.twig

Isn't the @AcmeDemoBundle syntax exclusively used for resources?
In this case I would suggest to omit the /Resources/ part always and just make the rest explicit, including the Bundle suffix.

{% javascripts '@AcmeFooBundle/public/js/*' %}
    <script type="text/javascript" src="{{ asset_url }}"></script>
{% endjavascripts %}

$this->render("@AcmeFooBundle/views/Test/a.html.twig");

@apfelbox Yes, the @ would be for templates, configuration files and (like you mentioned) asset files - I can't think of any non-resource items.

What you're saying is logical, but I don't think it is clear. It would also break backwards-compatability, so I don't think we can actually do it. I would rather recommend that we move things (views, config) out of the Resources directory. Then things are short, logical, and clear.

@cjunge-work I would be ok with the .html part still being there. I personally think we an do without it, but it doesn't bother me too much :).

From what have been said we currently have 3 ways of naming items using the namespaced way:

It's obvious that the Assetic naming and the configuration naming are built based on the combination of "@NameOfMyBundle" + "path to the resource". So if we really want to fix this issue from a UX point of view, why don't we just make Twig stick to this pattern ? In this case we would have something like @AcmeDemoBundle/Resources/views/Default/common/header.html.twig. Yes it's a bit longer, but like this there's no more confusion, they all look the same.

Pros :

• Consistency
• Explicitness
• Therefore: ease of explanation and usability

Cons :

• Longer paths
• Maybe some BC breaks or side effects I can't foresee ?

it indeed breaks BC (the WebProfilerBundle is using the current syntax). And longer paths are a drawback IMO

I agree with @apfelbox that the @... reference should simply be an alias for the Resources folder of a bundle. Then it's consistent wherever it is used. And it's also not unecessary long.
And IMO it makes sense because the Resource folder is meant for everything that is not PHP. And for PHP stuff we don't need @... syntax because there are other means like Namespaces and aliases.

@stof You're saying there's a BC break in @iamdto proposal? Can you give some more details? I see return '@Twig/Exception/'.($this->debug ? 'exception' : 'error').'.html.twig'; is used - but if we add a new @TwigBundle syntax (with the Bundle suffix) that points to a different directory, then no BC break. Right? Or is there something else?

@Tobion @apfelbox I don't disagree with the proposal to make @ point to Resources, but I don't think this is possible with a big BC break, since it will affect all assets and imported resources (and I don't see a way to be clever and support both). What do you say? This is part of the reason why I suggested moving things out of Resources/ entirely - that'd be just a new "suggestion" of how to organize things, but no BC break. I agree with Stof: longer paths are a drawback, especially when you always are typing Resources for all of your templates.

Thanks for everyone's thoughts!

@weaverryan I can't really follow you on the BC part: In your first paragraph you ask @stof to clarify why he thinks @Tobion's proposal isn't BC and in the second paragraph you explain why @Tobion's proposal isn't BC.

I would rather recommend that we move things (views, config) out of the Resources directory. Then things are short, logical, and clear.

I don't like this. The Resources dir is a really nice way to organize all files that aren't PHP files. The directory structure will get messy, since you would use both capitialized and lowercase dir names (Controllers vs views) and if we decide to capitialize views, we get confusion with View handlers. Besides that, there is no longer a clear difference between PHP and other files.

I like the @... syntax points to bundle_path/Resources, since it's exactly the goal of the @...: Having a way to "namespacify" the Resources dir of a bundle.

Let me throw in another idea: Abandon the @... from the config files and only use them in the templates using Twig's namespace feature. Use @webmozart's puli for the config:

# routing.yml
_acme_demo:
    resource: /acme/demo-bundle/config/routing.yml

@wouterj I fixed my comment :). I meant in @iamdto's proposal. I think (perhaps incorrectly) that Stof is saying that @iamdto's proposal has a BC break in it - but I don't see it. I definitely see a BC break in @Tobion's idea (though I don't dislike the idea!)

Just for curiosity I was looking at how do other technologies allow to access resources and I wanted to share three quick examples for comparison:

Objective-C

NSBundle *thisBundle = [NSBundle bundleForClass:[self class]];
commonDictionaryPath = [thisBundle pathForResource:@"CommonDictionary" ofType:@"plist"];

C#

// to access files stored inside the application package
var uri = new System.Uri("ms-appx:///images/logo.png");

// to access files stored in the application state
var uri = new System.Uri("ms-appdata:///local/images/logo.png");

Java / Spring Framework

Resource template = ctx.getResource("some/resource/path/myTemplate.txt);
Resource template = ctx.getResource("classpath:some/resource/path/myTemplate.txt);
Resource template = ctx.getResource("file:/some/resource/path/myTemplate.txt);
Resource template = ctx.getResource("http://myhost.com/resource/path/myTemplate.txt);

Based on these examples, we could think of new notations:

Explicit the type of resource you are loading

"view@AcmeDemoBundle/Default/index.html.twig"  // view@... looks for in Resources/views/
"conf@AcmeDemoBundle/services.xml"  // conf@... looks for in Resources/config/
"css@AcmeDemoBundle/styles.css"  // css@... looks for in Resources/public/css/

Allow to reference both the Resources/ and the root of the bundle

@AcmeDemoBundle/views/Default/index.html.twig
// one slash after bundle name equals to the Resources/ folder of that bundle

@AcmeDemoBundle//templates/index.html.twig
// two slashes after bundle name means the root of the bundle

Explicit the type of resource you are loading
In such cases I would suggest using Puli to make it look much nicer:

view://acme/demobundle/Default/index.html.twig
conf://acme/demobundle/routing.xml
public://acme/demobundle/css/styles.css (I would suggest *not* to target specific dirs in public)

@weaverryan I agree with @wouterj : I think that moving the /Resources/ one level up would be a mistake - it will clutter the bundle directory.

What I especially like about the @AcmeDemoBundle/views/... syntax is that it is very easy to grasp and explain. Especially if you market it as a the way to locate resources.

view://acme/demobundle/ seems to be way too specific. All I can do with that is what I can do with the @ notation, but the @ notation can do more (I assume that the list of possible values (view://, conf://, ...) would be a specified and limited list). An additional point is that view:// looks like a scheme, but isn't.

About the BC break: we shouldn't break BC for no gain. But to me it seems that this would be a good and big goal to achieve and we have 3.0 for BC breaks.

An additional note: this would be a BC break which on one hand has a quite large impact, but on the other hand is easily fixable (probably in an automated way).

Hi guys!

I wanted to keep this moving forward. Here is a summary:

1. People seem against moving views outside of Resources. I'm fine with that - I wasn't too sure about this either.

2. The challenge then is to have a syntax that is easy to understand, but which does not include typing Resources every time you want to render a template

It seems that we have a few competing ideas:

I'd like to not break BC mostly because it means we could put something into Symfony 2.6, whereas I think a BC break would need to be in 3.0 (which is fine, but would mean waiting).

I also thought about using something other than @. We might be able to protect BC on Kernel::locateResources by adding onto FileLocator::locate to look for some other syntax. It could potentially still use Kernel::locateResource, but we'd prefix the Resources/ on the path automatically. BC protected, just a new feature of this function. Can anyone see an issue here? Can we also make Twig namespaces work with something other than @? Or make Twig use the FileLocator::locate internally?

Thanks!

I don't want to remember the bundle name ,so I wrote a new class to replace render function
by render:
return $this->render('SolarHomepageBundle:Default:index.html.twig', $arr);
by my custom function:
return $this->render('Default/index', $arr);

note that the current @AcmeBlog/Default/index.html.twig is implemented using the builtin Twig feature, not using the kernel resource location

@alan-zhang- the issue with this is that the name of the template would need to know the location of the code using it to be able to resolve it. But PHP strings are not contextual. You cannot know where they have been created.

Why not @AcmeBlogBundle/Default/index.twig ? It's not always html ?

@fedir Twig allows you to have any output format you want. In my projects, I have some templates outputing plain text (for emails) and I have have a few templates output less markup.

TwigBundle will use the .<format>.twig convention to configure the autoescaping context

@stof Maybe we can make render function get the bundle name automatically. It's really a pain to remember the bundle name.
Here is my snippet to convert 'Default/index' to the full string with bundle name:

 private function getViewPath($view)
    {
        $bundleName = $this->getRequest()->attributes->get('_controller');
        $bundleName = str_replace('\', '', substr($bundleName, 0, strpos($bundleName, 'Bundle'))) . 'Bundle';
        if (strpos($view, '/') !== false) { // e.g. Auth/login.'
            $view = str_replace('/', ':', $view); // Auth:login
        } else { //e.g. login
            $view = ':' . $view;  // :login
        }
        if (strpos($view, '.') === false) { // omited .html.twig
            $view = $view . '.html.twig';
        }
        return $bundleName . ':' . $view;
    }

@alan-zhang- this could be a shortcut method in the controller, but it would not make Default/index the template name. The template name would still be AcmeDemoBundle:Default:index.html.twig in your case (try extending your template in Twig for instance)

@stof Yes, that's true. I wrapped this function in my custom base controller. Maybe it would be better if symphony can offer this shortcut in the BaseController. I think it's helpful for a lot users.

Removing .html. from 4 and 5 was actually an accident. I do like this change, but it does seem like most people are against it, so I think we should keep the .html. @javiereguiluz if you agree, can you modify the table above (I seem to have lost my ability to do that).

About this proposal: #11051 (comment)

I think it's very interesting. I had a conversation about this thread with some trainees a few weeks ago - asking them (new users) about the different options. And one actually said that it would be great if these "shortcuts" were explicitly configured somewhere (even if you get that configuration by default with the SE). So personally, I'm interested in exploring that option as well.

And yes, Twig already supports this with its namespace functionality (code blocks shown above). But I think one idea of this thread is to make a resource syntax that works everywhere. We don't necessarily need this, but a unifying syntax across all resources is one goal.

(Also @empire the answer to your question is here: http://symfony.com/doc/current/cookbook/templating/namespaced_paths.html#multiple-paths-per-namespace :) )

There are some details that need to be worked out with the explicit resources (namely, protecting BC for the current @AcmeDemoBundle behavior), but I want to see how people feel about it first.

Cheers!

Another point against the removal of .html: this would make the implementation of the template guessing in FrameworkExtraBundle (for @Template()) more complex, as it would then have to check multiple template names (with and without .html)

@weaverryan Thanks Ryan ;)

@weaverryan If I understand your comment:

one actually said that it would be great if these "shortcuts" were explicitly configured somewhere (even if you get that configuration by default with the SE). So personally, I'm interested in exploring that option as well.
...
There are some details that need to be worked out with the explicit resources (namely, protecting BC for the current @AcmeDemoBundle behavior), but I want to see how people feel about it first.

Do you mean that all bundles would have to explicitly define a namespace for their resources? Ie.

# Acme/AcmeBundle/resources/resources.yml  
resources:   
   AcmeBundle: src/Acme/AcmeBundle/Resources

If so, then I disagree. It's an easy convention to remember, and it's not confusing.

If it's as it is currently, then ignore my complaint :)

👍 @kingcrunch Also, an app/console resources:debug command might be a nice option to output all the built-in and customised resource mappings.

magic 👎 @kingcrunch 👍 👍 👍

@cjunge-work I really mean that we need to keep backwards-compatibility somehow. So if we introduced the syntax, then we'd probably need to continue to make @AcmeDemoBundle (or any bundle name) work (i.e. point exactly to the root path of that bundle), even if it doesn't appear in the resources configuration. I definitely wouldn't want to make the user do this for all bundles - that wouldn't be any fun :).

I do like this resources proposal by @kingcrunch, but does it solve our goals?

1. It does give us a unified syntax that could be used between views, configuration, etc. This was not a need for this issue, but it is nice.

2. It does not seem to give us a more understandable template rendering syntax. What resource would I register for my bundle? Something like this?

resources:
    MyCoolBundle_views: src/AcmeBundle/Resources/views

And then use:

return $this->render('@MyCoolBundle_views/Default/index.html.twig');

I'm not clear yet how I would use this feature to make rendering my templates make more sense, without something kind of ugly like MyCoolBundle_views. Thoughts?

When will this RFC close?

@weaverryan

2. I suggested to auto-assign the @FooBundle to the path path/to/FooBundle/Resources. Sure one can create a separate separate resource name @FooBundle_views pointing to ../Resources/view, when they want to confuse their users, although it doesn't make much sense.

Also imo it makes sense to disallow setting own resource names ending in Bundle to avoid any confusion.

@weaverryan @kingcrunch
I think we would have some default auto mapping and then some custom:

resources:
    views:  */Resources/views
    css:    */Resources/public/css
    myBase: MyBundle/Resources/views/base/common

If some day you want to change your base you just need to change the mapping.

I think is important to start with bundle name because we can have it in src or in vendor

👍 on 4

@felds This won't close at any specific time. In fact, if we can't find a better solution we agree on, we won't do anything :).

@kingcrunch I don't think we can map @FooBundle to path/to/FooBundle/Resources because it will break backwards compatibility. We would need to choose a different character besides @.

@ogimenezb How would your syntax end up looking then? @MyBundle:views/Default/index.html.twig? (like option 4 above)

@weaverryan yes, like 4.
The only "difference" is that you can have custom mapping.

resources:
    views:  */Resources/views
    css:    */Resources/public/css
    myBase: MyBundle/Resources/views/base/common

@MyBundle:views/Default/index.html.twig
@MyBundle:css/main.css.twig
@myBase/base.html.twig

What is the use-case for the custom mappings? Aren't we just going to end up replacing @FooBundle:views/* with something like @FooBundle_views:/*? Or are we talking about mapping these to non-Resource paths? Is it to ease the process of changing the "default" views bundle? For that, it seems to me that maybe editor search-replace would be more reliable. The only time search-replace wouldn't solve the issue is when you wanted to have multiple mappings to the same path.

However, I am generally supportive of increasing the transparency around the generation of these mappings.

@ryancastle The use case is, that you can refer to unbundled resources, at least was my intention, when I wrote it 😄

resources:
    # for example @bootstrap:js/affix.js
    # https://github.com/twbs/bootstrap/blob/master/js/affix.js
    bootstrap: %kernel.root_dir%/../vendor/twbs/bootstrap
    # Note, that I did _not_ include the js/ folder in the mapping
    # Because I want all resources from this component (css, maybe less, ...)

(This example doesn't make any assumptions about the syntax. It's just to clarify the use-case of custom resource path mappings)

I'ven chosen bootstrap as example, because it indeed as a composer.json and therefore it's somehow a real case. However, it should look more or less similar, when the resources are imported using other tools (like bower).

Imo it is pretty ugly to use custom mappings to point to a folder within a bundle folder. Following convention-over-configuration every bundled resource should be below Resources and if it's not there, it's not a resource of that bundle 😄 On the other hand it sounds just hacky to create bundles only to import external resources, like "bootstrap" mentioned above.

Interesting discussion. I am not as seasonned as most contributors here, but I have been a sf2 user for 3 years and sf1 before that, so I'll throw in my 2 cents.

First, I don't see much problem with the existing convention. Bundle:Controller:file is simple enough and makes sense. Even Bundle:Controller:my/complex/path/to/file is completely fine to me.

Now, if you guys are looking at changing that, and since this issue is related to directory structure, I'd like to rebound on @weaverryan 's questionning of the position of the views directory. As a matter of fact, one of the main things that has been tickling me in sf2 (and the devs I introduce to sf2) is the treatement of views and routing in the directory structure.

When I learned symfony2, 3 years ago, I read that everything starts with 3 fundamental things: a route, a controller and a template. Don't take my word for it, here is Ryan's ( http://symfony.com/doc/current/book/page_creation.html ). Indeed, routes, controllers and views are all you need to build a simple page. As such, it seems they should be treated as first class citizens.

Strangely when you look at directory structure, views (lowercase) are under Resources. When I think of Resources, it doesn't strike me as a "core component". In most people's mind, it's more likely to be associated with something external.

Routes are hidden even deeper, in Resources/config. I suppose you could see a route as a configuration, but really ? I prefer to see a routing as an independant component, separate from bundle configuration.

Obviously the current directory structure separates php from the other stuff. is that important ? Not to me. The views and routing are more essential than all sorts of directories you might find at the root ( Event, Helper, DataFixtures, Translation, etc.).

Long story short, I would like to throw in the blasphemous idea of moving Views (capitalized) and Routing to the bundle root.

Which, back to the current discussion, would make things nice and clear

AcmeBlogBundle:Views/Default/index.html.twig

or even

AcmeBlogBundle/Views/Default/index.html.twig

fitting directory structure.

I still very much agree with @kingcrunch and would love if we could find a solution based on it. It provides the perfect balance as an explicit, concise, configurable and customizable solution (imho).

As the creator of Puli, I'd like to weigh in here as I was designing Puli precisely to solve the problems discussed here.

I think that Puli would be a very nice and clean solution to most of the points I read here. Basically, Puli maps "virtual paths" to real paths in the file system, for example:

/app/ => /path/to/app/Resources/
/acme/demo-bundle/ => /path/to/demo-bundle/Resources/
...

With this mapping, you can easily refer to files in the Resources/ directories of different packages:

/app/config/config.yml
/acme/demo-bundle/views/layout.html.twig
/symfony/translation/messages.en.xlf

As a simple rule, you can specify that /app/ refers to the application's Resources/ directory and vendor/package to the Resources/ directory in the respective Composer package (that would be our rule, Puli itself doesn't care about it). This way, the mapping is easy to understand and "decode".

Additionally, Puli supports protocols to - for example - let you use full file system paths where you need them (similar to the Java examples above):

file:///absolute/path/to/config.yml
namespace:///Symfony/Component/Filesystem/Filesystem.php

Note that PHP's stream wrappers do not support URIs with less than two slashes, so URIs like file:/absolute/path/to/config.yml can't be used.

Last but not least, you can easily override individual files in Puli, for example:

/acme/demo-bundle/ => /path/to/demo-bundle/Resources/
/acme/demo-bundle/index.html.twig => /my/index.html.twig

I think this very simple architecture is very powerful and at the same time simple to understand. Being based on filesystem paths, relative paths are supported. For example, the following is currently not possible in Twig:

{% include 'somefile.html.twig' %}

# must be:
{% include 'ThisBundle:ThisController:somefile.html.twig' %}

Puli supports such a relative paths, and even paths like ../somefile.html.twig.

My 2 cents. :)

Closing it because we'll never reach an agreement. It's better to leave things as they are: Symfony supports several formats, they all work great and you can freely choose the one you prefer.