Merge branch '2.8' into 3.3

* 2.8:
  Mention and recommend to use PHP-CS-Fixer when contributing code
  Reworded the note about dump() availability per environment
  Fixed an example in the form testing article
  Improved the routing debug article

contributing/code/standards.rst

@@ -1,19 +1,33 @@
 Coding Standards
 ================
 
-When contributing code to Symfony, you must follow its coding standards. To
-make a long story short, here is the golden rule: **Imitate the existing
-Symfony code**. Most open-source Bundles and libraries used by Symfony also
-follow the same guidelines, and you should too.
+Symfony code is contributed by thousands of developers around the world. To make
+every piece of code look and feel familiar, Symfony defines some coding standards
+that all contributions must follow.
 
-Remember that the main advantage of standards is that every piece of code
-looks and feels familiar, it's not about this or that being more readable.
+These Symfony coding standards are based on the `PSR-1`_, `PSR-2`_ and `PSR-4`_
+standards, so you may already know most of them.
 
-Symfony follows the standards defined in the `PSR-0`_, `PSR-1`_, `PSR-2`_ and `PSR-4`_
-documents.
+Making your Code Follow the Coding Standards
+--------------------------------------------
 
-Since a picture - or some code - is worth a thousand words, here's a short
-example containing most features described below:
+Instead of reviewing your code manually, Symfony makes it simple to ensure that
+your contributed code matches the expected code syntax. First, install the
+`PHP CS Fixer tool`_ and then, run this command to fix any problem:
+
+.. code-block:: terminal
+
+    $ cd your-project/
+    $ php php-cs-fixer.phar fix -v
+
+If you forget to run this command and make a pull request with any syntax issue,
+our automated tools will warn you about that and will provide the solution.
+
+Symfony Coding Standards in Detail
+----------------------------------
+
+If you want to learn about the Symfony coding standards in detail, here's a
+short example containing most features described below:
 
 .. code-block:: html+php
 
@@ -122,7 +136,7 @@ example containing most features described below:
     }
 
 Structure
----------
+~~~~~~~~~
 
 * Add a single space after each comma delimiter;
 
@@ -181,7 +195,7 @@ Structure
 * Do not use spaces around ``[`` offset accessor and before ``]`` offset accessor.
 
 Naming Conventions
-------------------
+~~~~~~~~~~~~~~~~~~
 
 * Use camelCase, not underscores, for variable, function and method
   names, arguments;
@@ -228,7 +242,7 @@ Service Naming Conventions
   to ``something.service_name``).
 
 Documentation
--------------
+~~~~~~~~~~~~~
 
 * Add PHPDoc blocks for all classes, methods, and functions (though you may
   be asked to remove PHPDoc that do not add value);
@@ -239,14 +253,17 @@ Documentation
 
 * Omit the ``@return`` tag if the method does not return anything;
 
-* The ``@package`` and ``@subpackage`` annotations are not used.
+* The ``@package`` and ``@subpackage`` annotations are not used;
+
+* Inline the ``@inheritdoc`` tag.
 
 License
--------
+~~~~~~~
 
 * Symfony is released under the MIT license, and the license block has to be
   present at the top of every PHP file, before the namespace.
 
+.. _`PHP CS Fixer tool`: http://cs.sensiolabs.org/
 .. _`PSR-0`: http://www.php-fig.org/psr/psr-0/
 .. _`PSR-1`: http://www.php-fig.org/psr/psr-1/
 .. _`PSR-2`: http://www.php-fig.org/psr/psr-2/

form/unit_testing.rst

@@ -49,7 +49,8 @@ The simplest ``TypeTestCase`` implementation looks like the following::
 
             $form = $this->factory->create(TestedType::class);
 
-            $object = TestObject::fromArray($formData);
+            $object = new TestObject();
+            // ...populate $object properties with the data stored in $formData
 
             // submit the data to the form directly
             $form->submit($formData);

routing/debug.rst

@@ -6,18 +6,13 @@ How to Visualize And Debug Routes
 
 While adding and customizing routes, it's helpful to be able to visualize
 and get detailed information about your routes. A great way to see every
-route in your application is via the ``debug:router`` console command. Execute
-the command by running the following from the root of your project.
+route in your application is via the ``debug:router`` console command, which
+lists *all* the configured routes in your application:
 
 .. code-block:: terminal
 
     $ php bin/console debug:router
 
-This command will print a helpful list of *all* the configured routes in
-your application:
-
-.. code-block:: text
-
     ------------------ -------- -------- ------ ----------------------------------------------
      Name               Method   Scheme   Host   Path
     ------------------ -------- -------- ------ ----------------------------------------------
@@ -30,21 +25,18 @@ your application:
     ------------------ -------- -------- ------ ----------------------------------------------
 
 You can also get very specific information on a single route by including
-the route name after the command:
+the route name as the command argument:
 
 .. code-block:: terminal
 
     $ php bin/console debug:router article_show
 
-Likewise, if you want to test whether a URL matches a given route, you can
-use the ``router:match`` console command:
+Likewise, if you want to test whether a URL matches a given route, use the
+``router:match`` command. This is useful to debug routing issues and find out
+which route is associated with the given URL:
 
 .. code-block:: terminal
 
     $ php bin/console router:match /blog/my-latest-post
 
-This command will print which route the URL matches.
-
-.. code-block:: text
-
     Route "blog_show" matches

templating/debug.rst

@@ -46,8 +46,7 @@ The same mechanism can be used in Twig templates thanks to ``dump()`` function:
         </a>
     {% endfor %}
 
-By design, the ``dump()`` function is only available if the ``kernel.debug``
-setting (in ``config.yml``) is ``true``, to avoid leaking sensitive information
-in production. In fact, trying to use the ``dump()`` function when ``kernel.debug``
-is ``false`` (for example in the ``prod`` environment) will result in an
-application error.
+By design, the ``dump()`` function is only available in the ``dev`` and ``test``
+environments, to avoid leaking sensitive information in production. In fact,
+trying to use the ``dump()`` function in the ``prod`` environment will result in
+a PHP error.