Merge branch '2.3' into 2.7

Author: xabbuh

book/controller.rst

@@ -619,8 +619,8 @@ session.
 Flash Messages
 ~~~~~~~~~~~~~~
 
-You can also store small messages that will be stored on the user's session
-for exactly one additional request. This is useful when processing a form:
+You can also store small messages that will be stored on the user's session.
+This is useful when processing a form:
 you want to redirect and have a special message shown on the *next* page.
 These types of messages are called "flash" messages.
 
@@ -675,9 +675,17 @@ the ``notice`` message:
             </div>
         <?php endforeach ?>
 
-By design, flash messages are meant to live for exactly one request (they're
-"gone in a flash"). They're designed to be used across redirects exactly as
-you've done in this example.
+.. note::
+
+    By design, flash messages are meant to be processed exactly once. This means
+    that they vanish from the session automatically when they are retrieved from
+    the flash bag by calling the ``get()`` method.
+
+.. tip::
+
+    You can use the
+    :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::peek`
+    method instead to retrieve the message while keeping it in the bag.
 
 .. index::
    single: Controller; Response object

book/forms.rst

@@ -232,13 +232,21 @@ controller::
         $form->handleRequest($request);
 
         if ($form->isValid()) {
-            // perform some action, such as saving the task to the database
+            // ... perform some action, such as saving the task to the database
 
             return $this->redirectToRoute('task_success');
         }
 
-        // ...
+        return $this->render('default/new.html.twig', array(
+            'form' => $form->createView(),
+        ));
     }
+    
+.. caution::
+
+    Be aware that the ``createView()`` method should be called *after* ``handleRequest``
+    is called. Otherwise, changes done in the ``*_SUBMIT`` events aren't applied to the
+    view (like validation errors).
 
 .. versionadded:: 2.3
     The :method:`Symfony\\Component\\Form\\FormInterface::handleRequest` method

components/console/introduction.rst

@@ -143,8 +143,9 @@ Coloring the Output
     By default, the Windows command console doesn't support output coloring. The
     Console component disables output coloring for Windows systems, but if your
     commands invoke other scripts which emit color sequences, they will be
-    wrongly displayed as raw escape characters. Install the `ConEmu`_ or `ANSICON`_
-    free applications to add coloring support to your Windows command console.
+    wrongly displayed as raw escape characters. Install the `ConEmu`_, `ANSICON`_
+    or `Mintty`_ (used by default in GitBash and Cygwin) free applications
+    to add coloring support to your Windows command console.
 
 Whenever you output text, you can surround the text with tags to color its
 output. For example::
@@ -582,3 +583,4 @@ Learn More!
 .. _Packagist: https://packagist.org/packages/symfony/console
 .. _ConEmu: https://code.google.com/p/conemu-maximus5/
 .. _ANSICON: https://github.com/adoxa/ansicon/releases
+.. _Mintty: https://mintty.github.io/

contributing/code/tests.rst

@@ -51,8 +51,9 @@ what's going on and if the tests are broken because of the new code.
 
 .. tip::
 
-    On Windows, install the `ConEmu`_ or `ANSICON`_ free applications to see
-    colored test results.
+    On Windows, install the `ConEmu`_, `ANSICON`_ or `Mintty`_ free applications
+    to see colored test results.
 
 .. _ConEmu: https://code.google.com/p/conemu-maximus5/
 .. _ANSICON: https://github.com/adoxa/ansicon/releases
+.. _Mintty: https://mintty.github.io/

contributing/documentation/overview.rst

@@ -269,6 +269,11 @@ page on GitHub and click on ``Details``.
     ``.platform.app.yaml``, ``.platform/services.yaml`` and 
     ``.platform/routes.yaml`` allow `Platform.sh`_ to build Pull Requests.
 
+.. note::
+
+    Only Pull Requests to maintained branches are automatically built by
+    Platform.sh. Check the `roadmap`_ for maintained branches.
+
 Minor Changes (e.g. Typos)
 --------------------------
 
@@ -345,4 +350,5 @@ definitely don't want you to waste your time!
 .. _SensioLabsConnect: https://connect.sensiolabs.com/
 .. _`Symfony Documentation Badge`: https://connect.sensiolabs.com/badge/36/symfony-documentation-contributor
 .. _`sync your fork`: https://help.github.com/articles/syncing-a-fork
-.. _`Platform.sh`: https://platform.sh
+.. _`Platform.sh`: https://platform.sh
+.. _`roadmap`: https://symfony.com/roadmap

cookbook/email/dev_environment.rst

@@ -33,14 +33,15 @@ will not be sent when you run tests, but will continue to be sent in the
     .. code-block:: xml
 
         <!-- app/config/config_test.xml -->
-
-        <!--
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
-            http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd
-        -->
+            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
 
-        <swiftmailer:config
-            disable-delivery="true" />
+            <swiftmailer:config disable-delivery="true" />
+        </container>
 
     .. code-block:: php
 
@@ -70,13 +71,15 @@ via the ``delivery_address`` option:
     .. code-block:: xml
 
         <!-- app/config/config_dev.xml -->
-
-        <!--
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
-            http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd
-        -->
+            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
 
-        <swiftmailer:config delivery-address="dev@example.com" />
+            <swiftmailer:config delivery-address="dev@example.com" />
+        </container>
 
     .. code-block:: php
 
@@ -140,27 +143,32 @@ by adding the ``delivery_whitelist`` option:
             delivery_whitelist:
                # all email addresses matching this regex will *not* be
                # redirected to dev@example.com
-               - "/@specialdomain\.com$/"
+               - '/@specialdomain\.com$/'
 
                # all emails sent to admin@mydomain.com won't
                # be redirected to dev@example.com too
-               - "/^admin@mydomain\.com$/"
+               - '/^admin@mydomain\.com$/'
 
     .. code-block:: xml
 
         <!-- app/config/config_dev.xml -->
 
         <?xml version="1.0" charset="UTF-8" ?>
+        <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer">
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
 
-        <swiftmailer:config delivery-address="dev@example.com">
-            <!-- all email addresses matching this regex will *not* be redirected to dev@example.com -->
-            <swiftmailer:delivery-whitelist-pattern>/@specialdomain\.com$/</swiftmailer:delivery-whitelist-pattern>
+            <swiftmailer:config delivery-address="dev@example.com">
+                <!-- all email addresses matching this regex will *not* be redirected to dev@example.com -->
+                <swiftmailer:delivery-whitelist-pattern>/@specialdomain\.com$/</swiftmailer:delivery-whitelist-pattern>
 
-            <!-- all emails sent to admin@mydomain.com won't be redirected to dev@example.com too -->
-            <swiftmailer:delivery-whitelist-pattern>/^admin@mydomain\.com$/</swiftmailer:delivery-whitelist-pattern>
-        </swiftmailer:config>
+                <!-- all emails sent to admin@mydomain.com won't be redirected to dev@example.com too -->
+                <swiftmailer:delivery-whitelist-pattern>/^admin@mydomain\.com$/</swiftmailer:delivery-whitelist-pattern>
+            </swiftmailer:config>
+        </container>
 
     .. code-block:: php
 

cookbook/email/email.rst

@@ -41,17 +41,20 @@ already included:
     .. code-block:: xml
 
         <!-- app/config/config.xml -->
-
-        <!--
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
-            http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd
-        -->
-
-        <swiftmailer:config
-            transport="%mailer_transport%"
-            host="%mailer_host%"
-            username="%mailer_user%"
-            password="%mailer_password%" />
+            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+
+            <swiftmailer:config
+                transport="%mailer_transport%"
+                host="%mailer_host%"
+                username="%mailer_user%"
+                password="%mailer_password%"
+            />
+        </container>
 
     .. code-block:: php
 

cookbook/email/spool.rst

@@ -35,16 +35,17 @@ swiftmailer with the memory option, use the following configuration:
     .. code-block:: xml
 
         <!-- app/config/config.xml -->
-
-        <!--
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
-            http://symfony.com/schema/dic/swiftmailer
-            http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd
-        -->
+            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
 
-        <swiftmailer:config>
-             <swiftmailer:spool type="memory" />
-        </swiftmailer:config>
+            <swiftmailer:config>
+                <swiftmailer:spool type="memory" />
+            </swiftmailer:config>
+        </container>
 
     .. code-block:: php
 
@@ -73,18 +74,20 @@ In order to use the spool with a file, use the following configuration:
     .. code-block:: xml
 
         <!-- app/config/config.xml -->
-
-        <!--
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
-            http://symfony.com/schema/dic/swiftmailer
-            http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd
-        -->
-
-        <swiftmailer:config>
-             <swiftmailer:spool
-                 type="file"
-                 path="/path/to/spool" />
-        </swiftmailer:config>
+            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+
+            <swiftmailer:config>
+                <swiftmailer:spool
+                    type="file"
+                    path="/path/to/spool"
+                />
+            </swiftmailer:config>
+        </container>
 
     .. code-block:: php
 

cookbook/form/form_collections.rst

@@ -262,7 +262,7 @@ great, your user can't actually add any new tags yet.
 .. _cookbook-form-collections-new-prototype:
 
 Allowing "new" Tags with the "Prototype"
------------------------------------------
+----------------------------------------
 
 Allowing the user to dynamically add new tags means that you'll need to
 use some JavaScript. Previously you added two tags to your form in the controller.
@@ -417,6 +417,11 @@ into new ``Tag`` objects and added to the ``tags`` property of the ``Task`` obje
 
     You can find a working example in this `JSFiddle`_.
 
+.. seealso::
+
+    If you want to customize the HTML code in the prototype, read
+    :ref:`cookbook-form-custom-prototype`.
+
 To make handling these new tags easier, add an "adder" and a "remover" method
 for the tags in the ``Task`` class::
 

cookbook/form/form_customization.rst

@@ -739,6 +739,49 @@ You can also override the markup for an entire field row using the same method:
             <?php echo $view['form']->widget($form) ?>
         </div>
 
+.. _cookbook-form-custom-prototype:
+
+How to Customize a Collection Prototype
+---------------------------------------
+
+When using a :doc:`collection of forms </cookbook/form/form_collections>`,
+the prototype can be overridden with a completely custom prototype by
+overriding a block. For example, if your form field is named ``tasks``, you
+will be able to change the widget for each task as follows:
+
+.. configuration-block::
+
+    .. code-block:: html+jinja
+
+        {% form_theme form _self %}
+
+        {% block _tasks_entry_widget %}
+            <tr>
+                <td>{{ form_widget(task.task) }}</td>
+                <td>{{ form_widget(task.dueDate) }}</td>
+            </tr>
+        {% endblock %}
+
+    .. code-block:: html+php
+
+        <!-- src/AppBundle/Resources/views/Form/_tasks_entry_widget.html.php -->
+        <tr>
+            <td><?php echo $view['form']->widget($form->task) ?></td>
+            <td><?php echo $view['form']->widget($form->dueDate) ?></td>
+        </tr>
+
+Not only can you override the rendered widget, but you can also change the
+complete form row or the label as well. For the ``tasks`` field given above,
+the block names would be the following:
+
+================  =======================
+Part of the Form  Block Name
+================  =======================
+``label``         ``_tasks_entry_label``
+``widget``        ``_tasks_entry_widget``
+``row``           ``_tasks_entry_row``
+================  =======================
+
 Other common Customizations
 ---------------------------