Merge branch '2.8'

_theme/_templates/layout.html

@@ -46,7 +46,7 @@
                 <div id="demo-warning">
                     <h4>Pull request build</h4>
                     <p>Each pull request of the Symfony Documentation is automatically deployed and hosted on <a href="https://platform.sh">Platform.sh</a>.<br>
-                    Visit the page on <a href="https://symfony.com/doc/current/{{ pagename }}">symfony.com</a>.</p>
+                    View this page on <a href="https://symfony.com/doc/current/{{ pagename }}">symfony.com</a>.</p>
                 </div>
 
                 {%- include "globaltoc.html" %}

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

book/installation.rst

@@ -239,7 +239,7 @@ If there are any issues, correct them now before moving on.
         $ rm -rf app/cache/*
         $ rm -rf app/logs/*
 
-        $ HTTPDUSER=`ps aux | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root | head -1 | cut -d\  -f1`
+        $ HTTPDUSER=`ps axo user,comm | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root | head -1 | cut -d\  -f1`
         $ sudo chmod +a "$HTTPDUSER allow delete,write,append,file_inherit,directory_inherit" app/cache app/logs
         $ sudo chmod +a "`whoami` allow delete,write,append,file_inherit,directory_inherit" app/cache app/logs
 
@@ -254,7 +254,7 @@ If there are any issues, correct them now before moving on.
 
     .. code-block:: bash
 
-        $ HTTPDUSER=`ps aux | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root | head -1 | cut -d\  -f1`
+        $ HTTPDUSER=`ps axo user,comm | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root | head -1 | cut -d\  -f1`
         $ sudo setfacl -R -m u:"$HTTPDUSER":rwX -m u:`whoami`:rwX app/cache app/logs
         $ sudo setfacl -dR -m u:"$HTTPDUSER":rwX -m u:`whoami`:rwX app/cache app/logs
 

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/

components/options_resolver.rst

@@ -173,7 +173,7 @@ It's a good practice to split the option configuration into a separate method::
             $this->options = $resolver->resolve($options);
         }
 
-        protected function configureOptions(OptionsResolver $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             $resolver->setDefaults(array(
                 'host'       => 'smtp.example.org',
@@ -192,7 +192,7 @@ than processing options. Second, sub-classes may now override the
     // ...
     class GoogleMailer extends Mailer
     {
-        protected function configureOptions(OptionsResolver $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             parent::configureOptions($resolver);
 
@@ -215,7 +215,7 @@ For example, to make the ``host`` option required, you can do::
     {
         // ...
 
-        protected function configureOptions(OptionsResolver $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             // ...
             $resolver->setRequired('host');
@@ -243,7 +243,7 @@ one required option::
     {
         // ...
 
-        protected function configureOptions(OptionsResolver $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             // ...
             $resolver->setRequired(array('host', 'username', 'password'));
@@ -263,7 +263,7 @@ retrieve the names of all required options::
     // ...
     class GoogleMailer extends Mailer
     {
-        protected function configureOptions(OptionsResolver $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             parent::configureOptions($resolver);
 
@@ -291,7 +291,7 @@ been set::
     {
         // ...
 
-        protected function configureOptions(OptionsResolver $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             // ...
             $resolver->setRequired('host');
@@ -301,7 +301,7 @@ been set::
     // ...
     class GoogleMailer extends Mailer
     {
-        protected function configureOptions(OptionsResolver $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             parent::configureOptions($resolver);
 
@@ -336,7 +336,7 @@ correctly. To validate the types of the options, call
     {
         // ...
 
-        protected function configureOptions(OptionsResolver $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             // ...
             $resolver->setAllowedTypes('host', 'string');
@@ -381,7 +381,7 @@ to verify that the passed option contains one of these values::
     {
         // ...
 
-        protected function configureOptions(OptionsResolver $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             // ...
             $resolver->setDefault('transport', 'sendmail');
@@ -432,7 +432,7 @@ option. You can configure a normalizer by calling
     {
         // ...
 
-        protected function configureOptions(OptionsResolver $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             // ...
 
@@ -459,7 +459,7 @@ if you need to use other options during normalization::
     class Mailer
     {
         // ...
-        protected function configureOptions(OptionsResolver $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             // ...
             $resolver->setNormalizer('host', function ($options, $value) {
@@ -493,7 +493,7 @@ these options, you can return the desired default value::
     class Mailer
     {
         // ...
-        protected function configureOptions(OptionsResolver $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             // ...
             $resolver->setDefault('encryption', null);
@@ -525,7 +525,7 @@ the closure::
     class Mailer
     {
         // ...
-        protected function configureOptions(OptionsResolver $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             // ...
             $resolver->setDefaults(array(
@@ -537,7 +537,7 @@ the closure::
 
     class GoogleMailer extends Mailer
     {
-        protected function configureOptions(OptionsResolver $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             parent::configureOptions($resolver);
 
@@ -568,7 +568,7 @@ comes from the default::
     class Mailer
     {
         // ...
-        protected function configureOptions(OptionsResolver $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             // ...
             $resolver->setDefault('port', 25);
@@ -600,7 +600,7 @@ be included in the resolved options if it was actually passed to
     {
         // ...
 
-        protected function configureOptions(OptionsResolver $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             // ...
             $resolver->setDefined('port');
@@ -634,7 +634,7 @@ options in one go::
     class Mailer
     {
         // ...
-        protected function configureOptions(OptionsResolver $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             // ...
             $resolver->setDefined(array('port', 'encryption'));
@@ -655,7 +655,7 @@ let you find out which options are defined::
     {
         // ...
 
-        protected function configureOptions(OptionsResolver $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             parent::configureOptions($resolver);
 
@@ -701,7 +701,7 @@ can change your code to do the configuration only once per class::
             $this->options = self::$resolversByClass[$class]->resolve($options);
         }
 
-        protected function configureOptions(OptionsResolver $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             // ...
         }

components/var_dumper/introduction.rst

@@ -42,8 +42,9 @@ use instead of e.g. :phpfunction:`var_dump`. By using it, you'll gain:
 For example::
 
     require __DIR__.'/vendor/autoload.php';
+
     // create a variable, which could be anything!
-    $someVar = '...';
+    $someVar = ...;
 
     dump($someVar);
 
@@ -70,14 +71,14 @@ current PHP SAPI:
     #. Run ``composer global require symfony/var-dumper``;
     #. Add ``auto_prepend_file = ${HOME}/.composer/vendor/autoload.php``
        to your ``php.ini`` file;
-    #. From time to time, run ``composer global update`` to have the latest
-       bug fixes.
+    #. From time to time, run ``composer global update symfony/var-dumper``
+       to have the latest bug fixes.
 
 DebugBundle and Twig Integration
 --------------------------------
 
-The ``DebugBundle`` allows greater integration of the component into the
-Symfony full stack framework. It is enabled by default in the *dev* and *test*
+The DebugBundle allows greater integration of the component into the Symfony
+full-stack framework. It is enabled by default in the *dev* and *test*
 environment of the standard edition since version 2.6.
 
 Since generating (even debug) output in the controller or in the model
@@ -98,29 +99,9 @@ Choosing between both is mostly a matter of personal taste, still:
   be suited to your use case (e.g. you shouldn't use it in an HTML
   attribute or a ``<script>`` tag).
 
-By default for nested variables, dumps are limited to a subset of their
-original value. You can configure the limits in terms of:
-
-* maximum number of items to dump,
-* maximum string length before truncation.
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        debug:
-           max_items: 250
-           max_string_length: -1
-
-    .. code-block:: xml
-
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/debug"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/debug http://symfony.com/schema/dic/debug/debug-1.0.xsd">
-
-            <config max-items="250" max-string-length="-1" />
-        </container>
+This behavior can be changed by configuring the ``dump.dump_destination``
+option. Read more about this and other options in
+:doc:`the DebugBundle configuration reference </reference/configuration/debug>`.
 
 Using the VarDumper Component in your PHPUnit Test Suite
 --------------------------------------------------------

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