Twig template naming convention

[pulzarraider]

Correct me if I am wrong, but Symfony2 documentation does not specify if filename of Twig template should be written in camelCase (articleDetails.html.twig) or with underscores (article_details.html.twig).

In Symfony naming conventions is note:

Use alphanumeric characters and underscores for file names;

But in Including other templates doc section is mentioned template filename in camel case: articleDetails.html.twig

In the majority of open source bundles there are underscores used in template filenames (for example Sonata, KnpPaginatorBundle,MopaBootstrapBundle, GenemuFormBundle, AdmingeneratorGeneratorBundle), but some use camelCase filenames (FOSFacebookBundle) or they mix it together (for example FOSUserBundle, FOSMessageBundle).

So what`s the recommended way? This should be clearly explained in documentation.

Also Twig coding standars should be linked somewhere in documentation: http://twig.sensiolabs.org/doc/coding_standards.html

[Sydney-o9]

+1 This is a really good point! I would be very happy to know the answer to that question too.

[devhelp]

Same here, please explain it. I found another example in symfony documentation where camel case is used - http://symfony.com/doc/2.2/book/templating.html#embedding-controllers

[wouterj]

I find the 'use underscore for file names' pretty strange. Most of the filenames are the same as the class in the file (because of autoloading) and thus are camelCase...

I always use underscores for template file names, but I don't know if that is the standard. I'd like to know the opinion of more people and some core devs. before putting it in the docs.

As for the twig coding standards, I'm pretty sure it's mentioned somewhere. If it's not, create a PR which adds a .. tip:: directive somewhere at the start of book/templating.

[wouterj]

I created a poll to see which method people use: http://goo.gl/QSKwd

[ghost]

:+1: exactly what i'm looking for.

[fazy]

When does the poll close? I really don't mind either outcome, but I would like to standardise internal projects to match.

[devhelp]

@WouterJ I am also curious about the results

[wouterj]

will post the results tomorrow, together with a bundle survey.

[juliensnz]

+1 for me !

[wouterj]

As I promised. The poll result was 56% for underscores and 44% for pascalCase/camelCase.

Because it's so close, I took a look at the top bundles on knpbundles. I checked only the bundles which contain templates and in which you can see the use of underscores or pascalCase. It results in: 78% underscore, 7% pascalCase and 15% mix (e.g. userDefault_foo.html.twig)

I think it's save to say that using underscores is the way to standardize.

[stof]

I guess I can give one reason for the difference: shared bundles don't depend on SensioFrameworkExtraBundle, so they can name the template the way they want. People relying on the @Template annotation have to use pascalCase to match the action name.

[fazy]

@stof that's very interesting because it suggests it's not just a matter of preference but, if I understand correctly, there's an actual benefit to using pascalCase, i.e. you can just do @Template() instead of @Template("MyBundle:Controller:action_name.html.twig").

So, should the balance actually tip in favour of pascalCase? Or do we go with underscores but maybe do a PR for SensioFrameworkExtraBundle so it can guess based on _ names as well?

[ghost]

The point is, if pascalCase is used by @Template annotation, this should be a convention to naming the views. I'm wrong ?

[wouterj]

First of all, it's a convention and not a standard. That means that nobody have to follow it, it's just the recommend way.

@stof's reason seems to be a good one. We can do 2 things: (1) edit the filename conventions, it doesn't make sense nowadays as all file names of classes have uppercase letters in it or (2) request a change to the frameworkextrabundle to let it guess the pascalCase or the underscore version. I'm +1 for the first option.

[ArlingtonHouse]

In Mac OSX, all lowercase file names work locally for @Template, but fails when moving the project to an ubuntu server.

[xabbuh]

Can you give a reproducable example of what doesn't work on a Ubuntu server, @ArlingtonHouse?

[wouterj]

@ArlingtonHouse means that filenames are case-sensetive on linux, but case-insensetive on mac osx an windows.

[ArlingtonHouse]

Correct Wouter J. So a project using @Template like getcontactprofile.html.twig with the function getContactProfile works on Mac OSX but then fails when pushed to a linux server. It is a bit of a mess because the files can't be corrected in the Mac origin, they've go to be corrected in Linux and then pulled back to the Mac. It is a newbie gotcha but would be nice to enforce a convention here so that Symfony code works the same across platforms.

[xabbuh]

But that's more or less an OS related issue. The treatment of filenames is a thing where you as a developer need to be carefull to not mess things up totally. Even if there were conventions on template names it doesn't prevent you from accidentally using upercase characters in a file name which in turn lead you to the same problems.

[ArlingtonHouse]

Sure it is an OS issue, and it is pretty minor. The Twig docs have Camel Case examples so I think the problem is solved-- work started on this specific project 2 years ago and I stumbled into using all lower case. But in general having a convention for file naming is a good idea.

[ByScripts]

Eventually, it could be great to have an option, as for Doctrine table naming convention.

By default, for a ProductCategory entity, the table name will be ProductCategory.

But it's possible to change tant in app/config.yml (doctrine.orm.naming_strategy), and the table name will be product_category.

I would preferer to have the option to use by default underscore filenames.

/**
 * @Template
 */
public function thisIsMyAction() {}

would search for a template named this_is_my.html.twig

[stof]

@ByScripts Making a global configuration in SensioFrameworkExtraBundle means that the feature would become totally unusable for shared bundles, because they would not be able to know which naming convention is used. This would be a huge BC break for the bundle.

The Doctrine naming strategy being changed globally does not affect shared bundles much, because they generally don't write raw SQL but use DQL instead (and so the naming strategy will be used to create the query).

[ByScripts]

@stof You are right, but this could be configured at bundle level. CamelCasedFileNames are very annoying for me and my fellow workers ^^

[brian-lamb-software-engineer]

hmm.. i was searching for this very answer when i stumbled across this article. I personally dont like CamelCased file names either for templates. I just ran into an instance where i now need to make a decision. That last comment is the one that upset my balance, where as before i was going to just go with CamelCase, until i envisioned @ByScripts feelings. i still havent figured out the use of @Template but im sure this is key.

I think TWIG does need to have this mentioned as a convention on their site too, and i couldnt find it, which is why i landed here.

I may be going reluctantly with CamelCase.html.twig for now, but thats subject to change.

[stratease]

I too was looking for the answer to this question. In my humble opinion the standard really should follow the convention used for systems like the @Template() short hand. The community can help move the decision one way or another (with the poll), except when an convention is already in place by a related system. That should take precedence in this decision for continuity sake.

[brian-lamb-software-engineer]

wow im back already, after googling for yet another standard issue.
what case should i use on the blocks? i have a two worded block, and it doesnt look right to snake case them, but i think that may be what i will do.

by the way, i went with the much nicer looking snake_casing format for my templates as well. i leave the camelcasing for php classes, etc...

[stof]

I'm always using snake case for block names (same than for Twig variable names in the Twig coding standards)

[umpirsky]

@WouterJ Can you share pool results please?

[pulzarraider]

@umpirsky older pool results are in comment above

[wouterj]

The best practices have now clear guidelines on the naming of templates: http://symfony.com/doc/current/best_practices/templates.html

1. Do not use @Template
2. Always use lower case

I think this issue is solved now. If you disagree, please comment. GitHub does have a reopen button :)

[pulzarraider]

Thank you @WouterJ.

[OHB]

@WouterJ I don't see on the linked page where it talks about the naming of templates at all...it talks about the location of templates and all of the examples use index.html.twig. Unless I'm totally missing something but I don't see the word "lowercase", for example.

As a side question, how bad do people think it is to skip the standard in this case? I'm working on a project that necessarily has long twig names for partials (myspecialinterestingpartial.html.twig) and frankly I'd love to see that be mySpecialInterestingPartial.html.twig purely for readability. I can't see it as a cardinal sin to go that way but does anyone else have an opinion? (Can't do anything about the length of the names so don't ask)

[ghost]

Please reopen this issue. It's not solved as long as the decision is not documented in a place without ambiguity. As @OHB said, the linked Template chapter in the Symfony best practices does not talk about file names and does not contain the string "case".

[wouterj]

This will be fixed by: https://github.com/symfony/symfony-docs/pull/4779

[wouterj]

And it now also talks about naming :) Closing now

http://symfony.com/doc/current/best_practices/templates.html#template-locations

[leevigraham]

Latest doc link: https://symfony.com/doc/current/best_practices.html#templates

[abdellahrk]

Thank you @leevigraham, I sometimes get confused on this. Even being a long time Symfony dev.