Merge branch '2.3' into 2.7

* 2.3:
  [#6472] Updating description, after change
  Avoid confusion
  Added file paths
  Fixes and rewords
  Documented the config options of TwigBundle
  [#6427] Adding a header
  Tests: Explain how to add or remove data in a collection of forms
  Document constraint validator alias optional

Author: weaverryan

book/testing.rst

@@ -711,6 +711,51 @@ their type::
     PHP format (it converts the keys with square brackets notation - e.g.
     ``my_form[subject]`` - to PHP arrays).
 
+Adding and Removing Forms to a Collection
+.........................................
+
+If you use a :doc:`Collection of Forms </cookbook/form/form_collections>`,
+you can't add fields to an existing form with
+``$form['task[tags][0][name]'] = 'foo';``. This results in an error
+``Unreachable field "…"`` because ``$form`` can only be used in order to
+set values of existing fields. In order to add new fields, you have to
+add the values to the raw data array::
+
+    // Get the form.
+    $form = $crawler->filter('button')->form();
+
+    // Get the raw values.
+    $values = $form->getPhpValues();
+
+    // Add fields to the raw values.
+    $values['task']['tag'][0]['name'] = 'foo';
+    $values['task']['tag'][1]['name'] = 'bar';
+
+    // Submit the form with the existing and new values.
+    $crawler = $this->client->request($form->getMethod(), $form->getUri(), $values,
+        $form->getPhpFiles());
+
+    // The 2 tags have been added to the collection.
+    $this->assertEquals(2, $crawler->filter('ul.tags > li')->count());
+
+Where ``task[tags][0][name]`` is the name of a field created
+with JavaScript.
+
+You can remove an existing field, e.g. a tag::
+
+    // Get the values of the form.
+    $values = $form->getPhpValues();
+
+    // Remove the first tag.
+    unset($values['task']['tags'][0]);
+
+    // Submit the data.
+    $crawler = $client->request($form->getMethod(), $form->getUri(),
+        $values, $form->getPhpFiles());
+
+    // The tag has been removed.
+    $this->assertEquals(0, $crawler->filter('ul.tags > li')->count());
+
 .. index::
    pair: Tests; Configuration
 

book/translation.rst

@@ -440,10 +440,11 @@ need it::
             $request = $event->getRequest();
 
             // some logic to determine the $locale
-            $request->getSession()->set('_locale', $locale);
+            $request->setLocale($locale);
         }
 
-Read :doc:`/cookbook/session/locale_sticky_session` for more on the topic.
+Read :doc:`/cookbook/session/locale_sticky_session` for more information on making
+the user's locale "sticky" to their session.
 
 .. note::
 

cookbook/validation/custom_constraint.rst

@@ -167,7 +167,7 @@ Constraint Validators with Dependencies
 If your constraint validator has dependencies, such as a database connection,
 it will need to be configured as a service in the Dependency Injection
 Container. This service must include the ``validator.constraint_validator``
-tag and an ``alias`` attribute:
+tag and may include an ``alias`` attribute:
 
 .. configuration-block::
 
@@ -195,21 +195,14 @@ tag and an ``alias`` attribute:
             ->register('validator.unique.your_validator_name', 'Fully\Qualified\Validator\Class\Name')
             ->addTag('validator.constraint_validator', array('alias' => 'alias_name'));
 
-Your constraint class should now use this alias to reference the appropriate
-validator::
+As mentioned above, Symfony will automatically look for a class named after
+the constraint, with ``Validator`` appended. You can override this in your constraint class::
 
     public function validatedBy()
     {
-        return 'alias_name';
+        return 'Fully\Qualified\ConstraintValidator\Class\Name'; // or 'alias_name' if provided
     }
 
-As mentioned above, Symfony will automatically look for a class named after
-the constraint, with ``Validator`` appended. If your constraint validator
-is defined as a service, it's important that you override the
-``validatedBy()`` method to return the alias used when defining your service,
-otherwise Symfony won't use the constraint validator service, and will
-instantiate the class instead, without any dependencies injected.
-
 Class Constraint Validator
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 

reference/configuration/twig.rst

@@ -115,6 +115,76 @@ TwigBundle Configuration ("twig")
 Configuration
 -------------
 
+auto_reload
+~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``'%kernel.debug%'``
+
+If ``true``, whenever a template is rendered, Symfony checks first if its source
+code has changed since it was compiled. If it has changed, the template is
+compiled again automatically.
+
+autoescape_service
+~~~~~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``null``
+
+As of Twig 1.17, the escaping strategy applied by default to the template is
+determined during compilation time based on the filename of the template. This
+means for example that the contents of a ``*.html.twig`` template are escaped
+for HTML and the contents of ``*.js.twig`` are escaped for JavaScript.
+
+This option allows to define the Symfony service which will be used to determine
+the default escaping applied to the template.
+
+autoescape_service_method
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``null``
+
+If ``autoescape_service`` option is defined, then this option defines the method
+called to determine the default escaping applied to the template.
+
+base_template_class
+~~~~~~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``'Twig_Template'``
+
+Twig templates are compiled into PHP classes before using them to render
+contents. This option defines the base class from which all the template classes
+extend. Using a custom base template is discouraged because it will make your
+application harder to maintain.
+
+cache
+~~~~~
+
+**type**: ``string`` **default**: ``'%kernel.cache_dir%/twig'``
+
+Before using the Twig templates to render some contents, they are compiled into
+regular PHP code. Compilation is a costly process, so the result is cached in
+the directory defined by this configuration option.
+
+Set this option to ``null`` to disable Twig template compilation. However, this
+is not recommended; not even in the ``dev`` environment, because the
+``auto_reload`` option ensures that cached templates which have changed get
+compiled again.
+
+charset
+~~~~~~~
+
+**type**: ``string`` **default**: ``'%kernel.charset%'``
+
+The charset used by the template files. In the Symfony Standard edition this
+defaults to the ``UTF-8`` charset.
+
+debug
+~~~~~
+
+**type**: ``boolean`` **default**: ``'%kernel.debug%'``
+
+If ``true``, the compiled templates include a ``__toString()`` method that can
+be used to display their nodes.
+
 .. _config-twig-exception-controller:
 
 exception_controller
@@ -130,3 +200,128 @@ conditions (see :doc:`/cookbook/controller/error_pages`). Modifying this
 option is advanced. If you need to customize an error page you should use
 the previous link. If you need to perform some behavior on an exception,
 you should add a listener to the ``kernel.exception`` event (see :ref:`dic-tags-kernel-event-listener`).
+
+optimizations
+~~~~~~~~~~~~~
+
+**type**: ``int`` **default**: ``-1``
+
+Twig includes an extension called ``optimizer`` which is enabled by default in
+Symfony applications. This extension analyzes the templates to optimize them
+when being compiled. For example, if your template doesn't use the special
+``loop`` variable inside a ``for`` tag, this extension removes the initialization
+of that unused variable.
+
+By default, this option is ``-1``, which means that all optimizations are turned
+on. Set it to ``0`` to disable all the optimizations. You can even enable or
+disable these optimizations selectively, as explained in the Twig documentation
+about `the optimizer extension`_.
+
+paths
+~~~~~
+
+**type**: ``array`` **default**: ``null``
+
+This option defines the directories where Symfony will look for Twig templates
+in addition to the default locations (``app/Resources/views/`` and the bundles'
+``Resources/views/`` directories). This is useful to integrate the templates
+included in some library or package used by your application.
+
+The values of the ``paths`` option are defined as ``key: value`` pairs where the
+``value`` part can be ``null``. For example:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        twig:
+            # ...
+            paths:
+                '%kernel.root_dir%/../vendor/acme/foo-bar/templates': ~
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:twig="http://symfony.com/schema/dic/twig"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
+                                http://symfony.com/schema/dic/twig http://symfony.com/schema/dic/twig/twig-1.0.xsd">
+
+            <twig:config>
+                <!-- ... -->
+                <twig:path>%kernel.root_dir%/../vendor/acme/foo-bar/templates</twig:path>
+            </twig:config>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('twig', array(
+            // ...
+            'paths' => array(
+               '%kernel.root_dir%/../vendor/acme/foo-bar/templates' => null,
+            ),
+        ));
+
+The directories defined in the ``paths`` option have more priority than the
+default directories defined by Symfony. In the above example, if the template
+exists in the ``acme/foo-bar/templates/`` directory inside your application's
+``vendor/``, it will be used by Symfony.
+
+If you provide a value for any path, Symfony will consider it the Twig namespace
+for that directory:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        twig:
+            # ...
+            paths:
+                '%kernel.root_dir%/../vendor/acme/foo-bar/templates': 'foo_bar'
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:twig="http://symfony.com/schema/dic/twig"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
+                                http://symfony.com/schema/dic/twig http://symfony.com/schema/dic/twig/twig-1.0.xsd">
+
+            <twig:config>
+                <!-- ... -->
+                <twig:path namespace="foo_bar">%kernel.root_dir%/../vendor/acme/foo-bar/templates</twig:path>
+            </twig:config>
+        </container>
+
+    .. code-block:: php
+
+        # app/config/config.php
+        $container->loadFromExtension('twig', array(
+            // ...
+            'paths' => array(
+               '%kernel.root_dir%/../vendor/acme/foo-bar/templates' => 'foo_bar',
+            ),
+        ));
+
+This option is useful to not mess with the default template directories defined
+by Symfony. Besides, it simplifies how you refer to those templates:
+
+.. code-block:: text
+
+    @foo_bar/template_name.html.twig
+
+strict_variables
+~~~~~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``'%kernel.debug%'``
+
+If set to ``true``, Symfony shows an exception whenever a Twig variable,
+attribute or method doesn't exist. If set to ``false`` these errors are ignored
+and the non-existing values are replaced by ``null``.
+
+.. _`the optimizer extension`: http://twig.sensiolabs.org/doc/api.html#optimizer-extension