A month of Symfony Documentation #4 (March 2015)

With Symfony 2.7 feature freeze at the end of this month, lots of documentation about new features were merged. Besides this, the doc team focussed on fixing some issues and following the best practices.

New Documentation

Thomas Royer updated the whole documentation to use the shortcut methods that were added to the base Controller in Symfony 2.6. Among other methods, redirectToRoute(), denyAccessUnlessGranted() and addFlash() are now used in the documentation. He also made sure to remove the "magic" by documenting the long alternative in comments in the code.

David Buchmann also documented the base Controller methods, but now in the Controllers as Services article. He documented the required services and the code to use to replicate the methods yourself. This way, people no longer have to search trough Symfony source code when using controllers as services.

Javier Eguiluz and Wouter de Jong added two new best practices about custom form field types and template naming. Meanwhile, the Testing, Validation, Propel and HTTP cache book recipes were updated to follow the best practices.

The colors of the query count are now documented as well by "XitasoChris".

Helping during the Stabilisation Phase

With Symfony 2.7 now in stabilisation phase, the documentation team would like to get your help with documenting the missing bits. All issues that should be fixed before 2.7 is released can be found in the 2.7 milestone. These issues often contain a good explanation and aren't very hard to document. We hope to write your name in the overview of April!

Documentation Activity

This month, 67 PRs were merged and 23 new PRs were proposed. In total, the documentation recieved 2840 additions and 1445 deletions. This is made possible by the help of 53 different contributors.

A full list of changes can be found in the changelog.

The documentation is maintained by Ryan Weaver, Christian Flothmann and Wouter de Jong. The documentation repository can be found on GitHub.


Wouter, thanks as usual for the monthly digest. Now, let's work on documenting the new features of Symfony 2.7!
nice work :)
Great job!!! I loved the controllers shortcuts, mainly addFlash(). On the past I had a separated shortcut method in order to add flash messages. Now it isn't need anymore \o/
Hi, thanks for these digest, it's really helpful. Concerning the update about the templates naming, "Use lowercased snake_case for directory and template names", I'm quite confused about the directories in snake case. Even the app/Resources directory use capital letters (cache, logs... are all lowercase). Moreover the docs still exposes path like "AcmeDemoBundle:Default". Any hint ?

Thanks guys!

Thomas, the capitialized "Resource" directory name is indeed a bit strange. The reason behind it was probably to be consistent with "Resource" in a bundle directory structure, where it is capitialized to be consistent with the other directories. However, it'll be worth discussing changing it to lower case :)

In this case, the best practices are talking about everything following app/Resources. Such as app/Resources/blog_post/index.html.twig, app/Resources/blog_post/single.html.twig, etc.

About the AcmeDemoBundle:Default:... paths, the docs are still in the process of being updated to follow the best practices. It's quite a large documentation and it takes a lot of time and carefull thought to update it. If you find an occurence and have some time, we would really appreciate it if you hit the "edit" button and changed them to the best practices way!

Comments are closed.

To ensure that comments stay relevant, they are closed for old posts.