👍

@javiereguiluz Could you please link to the pull request where this feature has been implemented?

I'm -1, but could be persuaded :).

The problem isn't changing the docs, it's now that the internet will be showing 2 very different ways to render templates, and that will cause confusion. The official docs will now show a different rendering mechanism than years of blog posts on the web.

So even if the new syntax is a little bit more clear, the end result imo is much cloudier and confusing as people google for answers.

@xabbuh It should be #2211 :)

I tend to go in the same direction as @weaverryan. People are now used to the current syntax. We can introduce the new syntax, because it's slighty better, but then we have to explain the old syntax too. It's better to stick to one syntax for the docs and keep using that, except for cases where the old way is deprecated. But then, we have to add lots of versionadded directives.

We already have docs about this new way in http://symfony.com/doc/current/cookbook/templating/namespaced_paths.html. We may want to put that a little bit closer to the spotlight, by adding some references to it in templating related docs.

@weaverryan @wouterj I completely agree with your concerns!

However, as you say that you could be persuaded, let's talk about some similar changes that we made in the past:

• The {% include %} tag was replaced by the include() function (breaking lots of community resources)
• The with vendors/without vendors installation methods are about to be abandoned. The new Download page won't even mention them!
• The traditional VirtualHost based installation method is slowly being abandoned in favor of server:run command (the Getting Started tutorial doesn't explain VirtualHosts, only the server:run alternative ... and the official book will soon be updated).
• Forms have changed significantly in every Symfony major version from 2.0 to 2.4 (breaking every community resource)
• The default Symfony directory is going to (optionally) start changing from Symfony 2.5 onwards (see https://github.com/sensiolabs/SensioDistributionBundle/issues/117)

Lastly, although breaking community resources such as tutorials, blog posts, screencasts and books is definitely something to consider, please think that the new template naming is better, easier to explain and even faster to execute!

I will admit that beginners have a hard time understanding the AcmeDemoBundle:Default:index.html.twig syntax (and the _controller syntax).

What about the overriding templates using this? I thought I remembered hearing that a downside to the namespaces were that if 3rd party bundles used them, you couldn't override their templates in the traditional way. Or is that not an issue anymore? I realize we're teaching people how to develop their bundles (not 3rd party bundles), but I'd also like to stay consistent with how 3rd party bundles work. If this isn't an issue anymore and 3rd party bundles are moving towards this syntax, that would be a big plus.

I'm being persuaded... but not totally sure yet.

To be honest, I don't see why the @XxxBundle syntax is better than the XxxBundle:: syntax? I see that it is easier to understand for beginners and yeah, it might be quicker, but better?

You listed, except from the server:run item, all things that were deprecated or even removed in Symfony versions. The XxxBundle:: isn't removed, it still works. And, imo, it is still even good as @XxxBundle.

If we are going to update all docs to the @XxxBundle notation, we have to note everywhere why this is changed and how the new syntax works. That's needed when something is deprecated/removed, I'm not sure it's a good idea to make the docs more messy because something might be "better".

The same goes for controllers as services. We haven't updated the docs to that.

Also, the @XxxBundle syntax is confusing too, since it has multiple meanings:

• In a configuration file, @XxxBundle refers to src/Xxx/XxxBundle
• In a template, @XxxBundle refers to src/Xxx/XxxBundle/Resources/views
• In a controller, it depends on where you use it...

Wait I'm confused already too. In configuration files you will use @XxxBundle and in templates just @Xxx. That's going to hurt beginners :p

But as always, I just tell my opinion. If more people agree with your proposal, just do it :)

@wouterj I prefer @FoobarBundle/MyController/MyAction.html.twig because I'm able to copy MyController/MyAction.html.twig and past it the CTRL + P menu of sublime text. It's nothing, but I like it ;) Of course sublime text does not understand MyController:MyAction.html.twig because of the :. Then I save 5 characters huhu :D

@lyrixx you are confused too. Your path doesn't work, it should be @Foobar/MyController/MyAction.html.twig :)

On top of this, we loose the unified template name. Afaics, the @Xxx syntax isn't supported in PHP, so we have to keep using the old syntax for PHP and the new syntax for Twig.

@wouterj saying that the meaning of this notation changes in controllers / config files / templates is a bit cheating ... because in the old syntax it also changes.

Let me explain the big difference of the new notation using a real example. I've started to work as a Symfony trainer and one of the workshops is for the absolute beginners. Take a look at the differences between explaining the old and the new syntax.

Old syntax

Trainer  : This is the template naming syntax: Bundle:Controller:template
 Trainee : What is a controller?
Trainer  : We'll see it later. For now, it's a folder inside Resources/views/
 Trainee : So every template is associated with a controller.
Trainer  : Nope! You can create any folder inside Resources/views/
 Trainee : Then it's not the Controller folder
Trainer  : Sometimes it is and sometimes it's not
 Trainee : :|
           What if I create a common/ subfolder inside a controller?
           Will this syntax work? Bundle:Controller/common:template
Trainer  : Nope! It should be Bundle:Controller:common/template
 Trainee : But then, in the template notation syntax, the last part is not only
           the template name
Trainer  : Sometimes it is and sometimes it's not
 Trainee : :|

New syntax

Trainer  : To refer to template files stored in a Bundle, you just have to
           use the '@' symbol followed by the bundle name and followed by the
           template path starting from Resources/views/
           There are no exceptions. Ever.
 Trainee : Wow!! Really? Fantastic!!

Maybe I've exaggerated the last example ;) but hopefully I made my point.

Trainee : :| What if I create a common/ subfolder inside a controller? Will this syntax work? Bundle:Controller/common:template Trainer : Nope! It should be Bundle:Controller:common/template

This is wrong. Bundle:Controller/common:template and Bundle:Controller:common/template are strictly equivalent when resolving template names to their file names

This is wrong. Bundle:Controller/common:template and Bundle:Controller:common/template are strictly equivalent when resolving template names to their file names

Which obviously makes things worse because there is not an standard template naming. The problem with the old syntax is that the controller part can be:

• Empty
• A folder with the same name of a controller
• A folder with a different name of a controller
• A subfolder inside a folder with the name of a controller
• A subfolder inside a folder with a different name of a controller

With the new syntax there are no problems because there is no controller and no template ... just a template file path.

I don't like the Bundle:Controller:template explaination, Bundle:Directory:template is better imo. And then you just say "By convention, the Directory is the controller name." and your trainee is happy :)

With the new syntax: (slightly favoured in my opinion, just like you did 😉)

Trainer: "You have to use @ followed by the bundle name, without the bundle suffix."
Trainee: "But we already used @ suffixed with bundle name including Bundle suffix in the config. Why not here?"
Trainer: "Yeah, well. Symfony is confusing..."
Trainer: "Oh btw, if you render a PHP template, you have to use the Bundle:Dir:view syntax."
Trainee: "Wait, I've never heard about that syntax. Are there any docs for it?"
Trainer: "Yeah, take a look at the 2.0 docs, there it is explained!"

@wouterj again .... the differences with the @ symbol in configs, controllers and templates are the same in the old and in the new syntax. So there is no need to talk about them.

Regarding the PHP templates differences, to be honest I don't mind. There are millions of differences between PHP and Twig templates. And it's not crazy to think that Symfony 3.0 could remove the PHP templates altogether in favor of Twig.

@javiereguiluz The old syntax is less confusing when I read it as Bundle:Folder:file rather than Bundle:Controller:template. (this is also why I always use Bundle:Controller/common:template and not Bundle:Controller:common/template

Trainer: "Oh btw, if you render a PHP template, you have to use the Bundle:Dir:syntax."

Solution is simple: don't talk about PHP templates. See symfony/symfony#9193 (comment) if you need an argument

@stof "unfortunately", people read the official Symfony documentation. For instance, in this page you can read the following:

Symfony2 uses a bundle:controller:template string syntax for templates.

AcmeBlogBundle:Blog:index.html.twig
Blog: (controller) indicates that the template lives inside the Blog subdirectory of Resources/views;

AcmeBlogBundle::layout.html.twig
Since the middle, "controller", portion is missing [..]

As you can see, no mention of Directory and a lot of explanations about the Controller part.

@javiereguiluz The naming in the doc can also be changed. Isn't this discussion precisely about changing the way it is documented ?

Let's recap the pros and cons expressed so far:

Cons

• It would break all the community resources (books, tutorials, posts, screencats). This is a HUGE problem.
• It would create yet another difference between Twig and PHP templates, where this new notation is not supported.
• (Unconfirmed) It would make more difficult or even impossible to override third-party bundles' templates.

Pros

• It's easier to explain for newcomers.
• It has no exceptions (there are no empty parts inside the template name).
• It has no inconsistencies (templates are always the same, unlike Controller:subdir/template vs. Controller/subdir:template)
• It's "more native" (you can copy/paste paths and they work in your IDE vs. the special : syntax)
• It's faster to execute (negligible performance boost).
• (Updated by @stof) It works outside Symfony as well (in Silex for instance)

Another pro: it works when using Twig outside Symfony as well (in Silex for instance, which is exactly why the webProfilerBundle switched to it)

For the override of template, it works to overwrite templates in app/Resources/AcmeDemoBundle/views. It does not work to use a child bundle to overwrite the template (there is an issue about it)

The second format is more aligned with the syntax used in all Symfony code. This is important because provides integrity in the definition of a project and helps train new users of the tool.

But, Is true that changing something like that means maintaining of both formats along the time at least until the end of the oldest version support. Also change all documentation (which is no small).

This kind of decisions are like... "whatever you do, you'll be right".

You must do things with much impact

... so taking into account the cost of change, I do not think that's a good idea

It has no inconsistencies

I would like to mention that the new format is inconsistent with the existing resource syntax, as has been discussed before (can't find the discussion at the moment). I.e.

• Resource: @AcmeBlogBundle/Resources/views/Default/index.html.twig
• Template: @AcmeBlog/Default/index.html.twig

I personally find this subtle difference very prone to mistakes and thus prefer the colon syntax for templates.

@webmozart the inconsistencies of the old syntax mean that there is more than one way to name a template in this case:

• Resource: @AcmeBlogBundle/Resources/views/Default/common/template4.html.twig
• Template: AcmeBlogBundle : Default : common/template4.html.twig
• Also valid: AcmeBlogBundle : Default/common : template4.html.twig

With the new syntax, you always get the same value: @AcmeBlog/Default/common/template4.html.twig

Symfony project usually tries to remove inconsistencies and ambiguities like this one.

Another inconsistency of the old syntax: according to the official documentation, the middle part of the template naming is the controller part. The problem is that sometimes is a controller, sometimes is just a directory and sometimes is a directory inside a controller.

Another inconsistency of the old syntax: according to the official documentation, the middle part of the template naming is the controller part. The problem is that sometimes is a controller, sometimes is just a directory and sometimes is a directory inside a controller.

Again, this is not an inconsistency of the syntax, but an issue with the docs. Fix the docs to replace "Controller" with "Directory" and add a little sentence saying that by convention, the directory usually has the same name as the controller.

Fix the docs to replace "Controller" with "Directory"

... and we'll have again the first inconsistency: Directory sometimes is empty, sometimes is a Directory and sometimes is Directory/Subdirectory

we'll have again the first inconsistency: Directory sometimes is empty, sometimes is a Directory and sometimes is Directory/Subdirectory

And in all cases, it still refers to the directory :) Sometimes, there is no directory (so directory = empty), something there is a directory (so directory = directory) and sometimes, it's a subdirectory (so directory = subdirectory).

You can find inconsistencies in all things this way. Let's agree that we disagree and will never agree on this topic and let other people decide. So we keep to the raw facts, without a bit "Javier" or "Wouter" flavour:

Cons

• It would break all the community resources (books, tutorials, posts, screencats).
• It would create a difference between Twig and PHP templates.
• It does not work with overriding templates in child bundles
• It can easily be mixed up with the @AcmeDemoBundle notation

Pros

• It's easier to explain for newcomers.
• It makes the location more clear
• It doesn't have multiple ways to achieve the same thing (Bundle:Dir:subdir/template vs Bundle:Dir/subdir:template)
• It's "more native" (you can copy/paste paths and they work in your IDE vs. the special : syntax)
• It's faster to execute (negligible performance boost).
• It works outside Symfony as well (in Silex for instance)

(Unconfirmed) It would make more difficult or even impossible to override third-party bundles' templates.

This does not need to stay unconfirmed. I gave the answer in #3849 (comment)

thanks @stof, fixed it

Gosh, this is a hot debate. Now I'm leaning slightly towards the new syntax 😇

@webmozart Brought up the point about it being inconsistent with the resource importing (e.g. @MainBundle/Resources/config/foo.yml). I had actually been thinking the exact opposite - the new syntax feels nicely similar to this syntax. Of course, for templates, it still assumes Resources/views, and that inconsistency is unfortunate. Boy, if that inconsistency weren't there, it'd be a homerun...

I must say that I don't use the new namespaced syntax mostly because I don't see it used, and referenced to, in the documentation, and it's a shame because I find it more elegant and less error prone. All this Bundle:Controller/common:template Vs. Bundle:Controller:common/template always bothered me when I was a beginner, and if I remember correctly the former one was not even possible in the early years of Symfony (2.0 AFAIR).

So let's not get stuck in the past and let's move forward.

👍

@iamdto I agree with your comment, except for the last quote. Apparently, Facebook has realized that breaking things is not a good idea after all. At the most recent F8 conference: Facebook's era of breaking things is over

Here it is their new motto: "fast ... but stable"

You're right :)

Yea again, I'm actually +1 for this now - I think we need to be more aggressive with usability things. I would love to know if Fabien feels strongly one way or another - Javier have you chatted with him?

@weaverryan I haven't talked to him yet ... but let's ping him (@fabpot) to know his opinion about this discussion.

@weaverryan It's not just whether Resources/views is missing or not, but more importantly that one of the syntaxes omits the Bundle suffix and the other doesn't. That's the confusing part for me, as I find it hard to remember when to add the suffix and when not.

@weaverryan @webmozart I agree with Bernhard: we're trying to fix some inconsistencies by introducing a new one:

In configuration files: @AcmeDemoBundle/Resources/config/routing.yml
In templates: @AcmeDemo/Default/template3.html.twig

The inconsistency is introduced in this line of the TwigBundle. Maybe we could deprecate this behaviour and start registering namespaces with the Bundle suffix included?

Oh wow, I didn't even notice the missing Bundle - so yes, that is confusing! I don't like it!

I agree with @javiereguiluz - I would like to deprecate (if possible) the current behavior and require the Bundle suffix. I'm guessing there's no issue on that, can we create one?

Thanks - great conversation!

In general i'm 👍 in using the new syntax.
The main reason is simply that the old style uses both : and / as seperators. And it's just unneeded and puts confusing on which part to put where. The new style just uses / which everyone knows from path traversal.

It does not work with overriding templates in child bundles

What does this actually mean? I guess it's about symfony/symfony#9085

It can easily be mixed up with the @AcmeDemoBundle notation

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

The "Bundle" suffix was probably left out to be as short as possible. We could do the same for resources. The question is when somebody uses a Bundle without the Bundle suffix, which consequences would that have on our naming scheme? If the references still work even when the Bundle doesn't follow the standard naming scheme, it would be good.

@javiereguiluz now we have the best practices, do you still think this issue is relevant? (especially since we updated the Templating book chapter to make things as clear as possible?)

In my opinion we should always use the best-practice notation (default/index.html.twig), except when, for any given reason, we cannot. In those cases, I suggest to use the namespaced syntax (@AppBundle/Default/index.html.twig). I also suggest to never again use, mention, explain or show the three-parts-separated-with-colons syntax (AppBundle:Default:index.html.twig).

@javiereguiluz I know this issue and (symfony/symfony#11051) got a little crazy, but I think we're close now - and I agree with what you said above.

But, the core code is still stripping off the Bundle suffix in the Twig namespaces (remember this code? https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/TwigBundle/DependencyInjection/TwigExtension.php#L130-132). If I'm correct, then we need to:

A) Deprecate the @AcmeDemo/Default/index.html.twig namespace
B) Add the @AcmeDemoBundle/Default/index.html.twig namespace
C) Start using the syntax in (B) instead of the 3-part syntax (?does it have any downsides - can you use bundle-overriding with it? I can't remember).

Also - I want to keep things focused - but this plan could possibly be changed if we imagine using puli in Symfony 3.0. In that case, we'd need to brain-storm how that would look and move in that direction instead of moving towards (B) and (C) above (cc @webmozart).

Make sense?

@weaverryan I would like to work on Puli integration directly into Symfony once 2.7 is released, as the feature freeze is too soon now. Also this means that a stable version of Puli will be available.

For reference, with Puli the paths will be normalized to:

/acme/blog-bundle/views/Default/common/template4.html.twig

If a resource is loaded through Puli (e.g. a Twig template or a config file), references to other resources can use relative paths:

../views/Default/common/template4.html.twig

@webmozart what would be the Puli path for a template stored in the global app/Resources/views/ directory? (e.g. app/Resources/views/common/template4.html.twig)

And I have another question: since you already have tested some proof-of-concept integrations of Puli + Symfony: what's the impact of Puli on performance? (I'm not implying that Puli degrades performance ... I'm just curious to know if Puli improves or degrades or maintains Symfony performance). Thanks.

@javiereguiluz The application path for your example would be:

/app/views/common/template4.html.twig

For DX reasons, I even think we should get rid of the Resources directory in applications. Then the Puli path is the same as the relative path to the project root.

At the moment, Puli degrades performance directly after clearing the cache. This needs to be optimized. Once the cache is loaded, performance is the same as now, since Puli is not accessed anymore then.

Closing this issue because there is no consensus to make this change.

In any case, docs already use the syntax recommended by the Symfony Best Practices for global templates and the traditional syntax (Bundle:controller:template) for the few bundle templates.