Merge branch '2.7'

* 2.7: (38 commits)
  Update configuration.rst
  Update configuration.rst
  Readability
  [#4875] Minor language tweaks
  [#4779] Minor tweaks to a huge PR
  [#4724] Minor language tweaks and cross-link to form theming
  [Serializer] Fix CS
  document the validation payload option
  Fixed some of the comments
  [#4793] Very minor tweak that sounds more natural
  [#4732] Tweaking language, clarifying purpose of disabling form and that you can disable CSRF on 1 form
  [#4732] Tweaking language, clarifying purpose of disabling form and that you can disable CSRF on 1 form
  [config][translator] use the new fallbacks option.
  add missing reference options and descriptions
  Linked "logrotate" to its official website
  Minor rewording
  Added a note about log file sizes and the use of logrotate
  Use snake_case for template names
  Fixed minor grammar issues
  Made http cache chapter best-practices-compatible and lots of other fixes
  ...

best_practices/configuration.rst

@@ -42,6 +42,8 @@ they have nothing to do with the application's behavior. In other words, your
 application doesn't care about the location of your database or the credentials
 to access to it, as long as the database is correctly configured.
 
+.. _best-practices-canonical-parameters:
+
 Canonical Parameters
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -101,8 +103,8 @@ to control the number of posts to display on the blog homepage:
     parameters:
         homepage.num_items: 10
 
-If you ask yourself when the last time was that you changed the value of
-*any* option like this, odds are that you *never* have. Creating a configuration
+If you've done something like this in the past, it's likely that you've in fact
+*never* actually needed to change that value. Creating a configuration
 option for a value that you are never going to configure just isn't necessary.
 Our recommendation is to define these values as constants in your application.
 You could, for example, define a ``NUM_ITEMS`` constant in the ``Post`` entity:

best_practices/i18n.rst

@@ -11,7 +11,7 @@ following ``translator`` configuration option and set your application locale:
     # app/config/config.yml
     framework:
         # ...
-        translator: { fallback: "%locale%" }
+        translator: { fallbacks: ["%locale%"] }
 
     # app/config/parameters.yml
     parameters:

best_practices/templates.rst

@@ -51,6 +51,10 @@ Another advantage is that centralizing your templates simplifies the work
 of your designers. They don't need to look for templates in lots of directories
 scattered through lots of bundles.
 
+.. best-practice::
+
+    Use lowercased snake_case for directory and template names.
+
 Twig Extensions
 ---------------
 

book/controller.rst

@@ -471,14 +471,14 @@ If you're serving HTML, you'll want to render a template. The ``render()``
 method renders a template **and** puts that content into a ``Response``
 object for you::
 
-    // renders app/Resources/views/Hello/index.html.twig
-    return $this->render('Hello/index.html.twig', array('name' => $name));
+    // renders app/Resources/views/hello/index.html.twig
+    return $this->render('hello/index.html.twig', array('name' => $name));
 
 You can also put templates in deeper sub-directories. Just try to avoid creating
 unnecessarily deep structures::
 
-    // renders app/Resources/views/Hello/Greetings/index.html.twig
-    return $this->render('Hello/Greetings/index.html.twig', array('name' => $name));
+    // renders app/Resources/views/hello/greetings/index.html.twig
+    return $this->render('hello/greetings/index.html.twig', array('name' => $name));
 
 The Symfony templating engine is explained in great detail in the
 :doc:`Templating </book/templating>` chapter.

book/forms.rst

@@ -96,7 +96,7 @@ from inside a controller::
                 ->add('save', 'submit', array('label' => 'Create Task'))
                 ->getForm();
 
-            return $this->render('Default/new.html.twig', array(
+            return $this->render('default/new.html.twig', array(
                 'form' => $form->createView(),
             ));
         }
@@ -144,14 +144,14 @@ helper functions:
 
     .. code-block:: html+jinja
 
-        {# app/Resources/views/Default/new.html.twig #}
+        {# app/Resources/views/default/new.html.twig #}
         {{ form_start(form) }}
         {{ form_widget(form) }}
         {{ form_end(form) }}
 
     .. code-block:: html+php
 
-        <!-- app/Resources/views/Default/new.html.php -->
+        <!-- app/Resources/views/default/new.html.php -->
         <?php echo $view['form']->start($form) ?>
         <?php echo $view['form']->widget($form) ?>
         <?php echo $view['form']->end($form) ?>
@@ -442,12 +442,12 @@ corresponding errors printed out with the form.
 
        .. code-block:: html+jinja
 
-           {# app/Resources/views/Default/new.html.twig #}
+           {# app/Resources/views/default/new.html.twig #}
            {{ form(form, {'attr': {'novalidate': 'novalidate'}}) }}
 
        .. code-block:: html+php
 
-           <!-- app/Resources/views/Default/new.html.php -->
+           <!-- app/Resources/views/default/new.html.php -->
            <?php echo $view['form']->form($form, array(
                'attr' => array('novalidate' => 'novalidate'),
            )) ?>
@@ -788,7 +788,7 @@ of code. Of course, you'll usually need much more flexibility when rendering:
 
     .. code-block:: html+jinja
 
-        {# app/Resources/views/Default/new.html.twig #}
+        {# app/Resources/views/default/new.html.twig #}
         {{ form_start(form) }}
             {{ form_errors(form) }}
 
@@ -798,7 +798,7 @@ of code. Of course, you'll usually need much more flexibility when rendering:
 
     .. code-block:: html+php
 
-        <!-- app/Resources/views/Default/newAction.html.php -->
+        <!-- app/Resources/views/default/newAction.html.php -->
         <?php echo $view['form']->start($form) ?>
             <?php echo $view['form']->errors($form) ?>
 
@@ -1006,12 +1006,12 @@ to the ``form()`` or the ``form_start()`` helper:
 
     .. code-block:: html+jinja
 
-        {# app/Resources/views/Default/new.html.twig #}
+        {# app/Resources/views/default/new.html.twig #}
         {{ form_start(form, {'action': path('target_route'), 'method': 'GET'}) }}
 
     .. code-block:: html+php
 
-        <!-- app/Resources/views/Default/newAction.html.php -->
+        <!-- app/Resources/views/default/newAction.html.php -->
         <?php echo $view['form']->start($form, array(
             'action' => $view['router']->generate('target_route'),
             'method' => 'GET',
@@ -1470,7 +1470,7 @@ renders the form:
 
     .. code-block:: html+jinja
 
-        {# app/Resources/views/Default/new.html.twig #}
+        {# app/Resources/views/default/new.html.twig #}
         {% form_theme form 'form/fields.html.twig' %}
 
         {% form_theme form 'form/fields.html.twig' 'form/fields2.html.twig' %}
@@ -1479,10 +1479,10 @@ renders the form:
 
     .. code-block:: html+php
 
-        <!-- app/Resources/views/Default/new.html.php -->
-        <?php $view['form']->setTheme($form, array('Form')) ?>
+        <!-- app/Resources/views/default/new.html.php -->
+        <?php $view['form']->setTheme($form, array('form')) ?>
 
-        <?php $view['form']->setTheme($form, array('Form', 'Form2')) ?>
+        <?php $view['form']->setTheme($form, array('form', 'form2')) ?>
 
         <!-- ... render the form -->
 
@@ -1780,6 +1780,8 @@ The CSRF token can be customized on a form-by-form basis. For example::
         // ...
     }
 
+.. _form-disable-csrf:
+
 To disable CSRF protection, set the ``csrf_protection`` option to false.
 Customizations can also be made globally in your project. For more information,
 see the :ref:`form configuration reference <reference-framework-form>`

book/from_flat_php_to_symfony2.rst

@@ -710,7 +710,7 @@ for example, the list template written in Twig:
 
 .. code-block:: html+jinja
 
-    {# app/Resources/views/Blog/list.html.twig #}
+    {# app/Resources/views/blog/list.html.twig #}
     {% extends "layout.html.twig" %}
 
     {% block title %}List of Posts{% endblock %}