Merge branch '3.3' into 3.4

* 3.3: (23 commits)
  Renamed the channel to "app"
  Add XmlEncoder documentation with $context available options
  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
  Mention that we are using Bootstrap Datepicker
  Remove information about default priority
  Fix missing blank line
  Add note about LocaleListener
  ...

Author: javiereguiluz

components/serializer.rst

@@ -864,6 +864,63 @@ you indicate that you're expecting an array instead of a single object.
     $data = ...; // The serialized data from the previous example
     $persons = $serializer->deserialize($data, 'Acme\Person[]', 'json');
 
+The ``XmlEncoder``
+------------------
+
+This encoder transforms arrays into XML and vice versa. For example, take an
+object normalized as following::
+
+    array('foo' => array(1, 2), 'bar' => true);
+
+The ``XmlEncoder`` encodes this object as follows:
+
+.. code-block:: xml
+
+    <?xml version="1.0"?>
+    <response>
+        <foo>1</foo>
+        <foo>2</foo>
+        <bar>1</bar>
+    </response>
+
+The array keys beginning with ``@`` are considered XML attributes::
+
+    array('foo' => array('@bar' => 'value'));
+
+    // is encoded as follows:
+    // <?xml version="1.0"?>
+    // <response>
+    //     <foo bar="value" />
+    // </response>
+
+Context
+~~~~~~~
+
+The ``encode()`` method defines a third optional parameter called ``context``
+which defines the configuration options for the XmlEncoder an associative array::
+
+    $xmlEncoder->encode($array, 'xml', $context);
+
+These are the options available:
+
+``xml_format_output``
+    If set to true, formats the generated XML with line breaks and indentation.
+
+``xml_version``
+    Sets the XML version attribute (default: ``1.1``).
+
+``xml_encoding``
+    Sets the XML encoding attribute (default: ``utf-8``).
+
+``xml_standalone``
+    Adds standalone attribute in the generated XML (default: ``true``).
+
+``xml_root_node_name``
+    Sets the root node name (default: ``response``).
+
+``remove_empty_tags``
+    If set to true, removes all empty tags in the generated XML.
+
 Recursive Denormalization and Type Safety
 -----------------------------------------
 

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);

reference/dic_tags.rst

@@ -658,7 +658,7 @@ channel when injecting the logger in a service.
             AppBundle\Log\CustomLogger:
                 arguments: ['@logger']
                 tags:
-                    - { name: monolog.logger, channel: acme }
+                    - { name: monolog.logger, channel: app }
 
     .. code-block:: xml
 
@@ -671,7 +671,7 @@ channel when injecting the logger in a service.
             <services>
                 <service id="AppBundle\Log\CustomLogger">
                     <argument type="service" id="logger" />
-                    <tag name="monolog.logger" channel="acme" />
+                    <tag name="monolog.logger" channel="app" />
                 </service>
             </services>
         </container>
@@ -683,7 +683,7 @@ channel when injecting the logger in a service.
 
         $container->register(CustomLogger::class)
             ->addArgument(new Reference('logger'))
-            ->addTag('monolog.logger', array('channel' => 'acme'));
+            ->addTag('monolog.logger', array('channel' => 'app'));
 
 .. tip::
 

reference/forms/types/date.rst

@@ -108,7 +108,7 @@ picker:
 
     <script>
         $(document).ready(function() {
-            // configure the bootstrap datepicker
+            // you may need to change this code if you are not using Bootstrap Datepicker
             $('.js-datepicker').datepicker({
                 format: 'yyyy-mm-dd'
             });

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

service_container.rst

@@ -371,9 +371,8 @@ made. To do that, you create a new class::
                 ->addPart(
                     'Someone just updated the site. We told them: '.$happyMessage
                 );
-            $this->mailer->send($message);
-
-            return $happyMessage;
+            
+            return $this->mailer->send($message) > 0;
         }
     }
 
@@ -387,8 +386,10 @@ you can use the service immediately::
     {
         // ...
 
-        $message = $siteUpdateManager->notifyOfSiteUpdate();
-        $this->addFlash('success', $message);
+        if ($siteUpdateManager->notifyOfSiteUpdate()) {
+            $this->addFlash('success', 'Notification mail was sent successfully.');
+        }
+        
         // ...
     }
 

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.

translation/locale.rst

@@ -26,6 +26,13 @@ it::
             $request->setLocale($locale);
         }
 
+.. note::
+
+    The custom listener must be called **before** ``LocaleListener``, which
+    initializes the locale based on the current request. To do so, set your
+    listener priority to a higher value than ``LocaleListener`` priority (which
+    you can obtain running the ``debug:event kernel.request`` command).
+
 Read :doc:`/session/locale_sticky_session` for more information on making
 the user's locale "sticky" to their session.