Merge branch '2.8' into 3.2

* 2.8: (24 commits)
  Update optional_dependencies.rst
  Fix xml blocks
  pass only strings to loadUserByUsername()
  Fix Authenticator Class (getCredentials) example
  Added the picture that shows how GuardAuthenticationListener calls Authentication Guard methods.
  [#7875] minor tweaks
  Minor fix
  Minor changes
  [#7773] fix line length
  Add helpful remarks on custom DataCollector
  Remove use of deprecated security.exception_listener.class parameter
  Update resources.rst
  Fix incoherent ut8mb4 collation in Doctrine setup
  Fix decorating service definition
  fix empty XML element
  [#7873] add missing toctree entries
  Reworded the introduction of the contributing docs
  [HttpFoundation] Fix clearstatcache first arg
  Explain how to provide a stack trace
  Add link to the Slack support channel
  ...

Author: xabbuh

_images/security/authentication-guard-methods.png

@@ -348,9 +348,17 @@ The end user can provide values in any configuration file:
     .. code-block:: xml
 
         <!-- app/config/config.xml -->
-        <parameters>
-            <parameter key="acme_blog.author.email">fabien@example.com</parameter>
-        </parameters>
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <parameters>
+                <parameter key="acme_blog.author.email">fabien@example.com</parameter>
+            </parameters>
+
+        </container>
 
     .. code-block:: php
 

bundles/best_practices.rst

@@ -225,7 +225,7 @@ thrown)::
         $configuration = new Configuration();
 
         $config = $this->processConfiguration($configuration, $configs);
-        
+
         // you now have these 2 config keys
         // $config['twitter']['client_id'] and $config['twitter']['client_secret']
     }
@@ -424,7 +424,6 @@ Assuming the XSD file is called ``hello-1.0.xsd``, the schema location will be
 
     <!-- app/config/config.xml -->
     <?xml version="1.0" ?>
-
     <container xmlns="http://symfony.com/schema/dic/services"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:acme-hello="http://acme_company.com/schema/dic/hello"

bundles/configuration.rst

@@ -12,7 +12,7 @@ users to choose to remove functionality they are not using. Creating multiple
 bundles has the drawback that configuration becomes more tedious and settings
 often need to be repeated for various bundles.
 
-It is possible to remove the disadvantage of the multiple bundle approach 
+It is possible to remove the disadvantage of the multiple bundle approach
 by enabling a single Extension to prepend the settings for any bundle.
 It can use the settings defined in the ``app/config/config.yml``
 to prepend settings just as if they had been written explicitly by
@@ -116,11 +116,21 @@ The above would be the equivalent of writing the following into the
     .. code-block:: xml
 
         <!-- app/config/config.xml -->
-        <acme-something:config use-acme-goodbye="false">
-            <acme-something:entity-manager-name>non_default</acme-something:entity-manager-name>
-        </acme-something:config>
+        <?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:acme-something="http://example.org/schema/dic/acme_something"
+            xmlns:acme-other="http://example.org/schema/dic/acme_other"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
 
-        <acme-other:config use-acme-goodbye="false" />
+            <acme-something:config use-acme-goodbye="false">
+                <acme-something:entity-manager-name>non_default</acme-something:entity-manager-name>
+            </acme-something:config>
+
+            <acme-other:config use-acme-goodbye="false" />
+
+        </container>
 
     .. code-block:: php
 

bundles/prepend_extension.rst

@@ -523,7 +523,7 @@ Please note that this will not work when the ``X-Sendfile`` header is set.
 
     If you *just* created the file during this same request, the file *may* be sent
     without any content. This may be due to cached file stats that return zero for
-    the size of the file. To fix this issue, call ``clearstatcache(false, $file)``
+    the size of the file. To fix this issue, call ``clearstatcache(true, $file)``
     with the path to the binary file.
 
 .. _component-http-foundation-json-response:

components/http_foundation.rst

@@ -45,7 +45,7 @@ In this example, the validation metadata is retrieved executing the
         public static function loadValidatorMetadata(ClassMetadata $metadata)
         {
             $metadata->addPropertyConstraint('name', new Assert\NotBlank());
-            $metadata->addPropertyConstraint('name', new Asert\Length(array(
+            $metadata->addPropertyConstraint('name', new Assert\Length(array(
                 'min' => 5,
                 'max' => 20,
             )));

components/validator/resources.rst

@@ -69,11 +69,22 @@ accomplished easily and transparently:
 
     .. code-block:: xml
 
-        <imports>
-            <import resource="config.xml" />
-        </imports>
+        <?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:doctrine="http://symfony.com/schema/dic/doctrine"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/doctrine
+                http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
 
-        <!-- ... -->
+            <imports>
+                <import resource="config.xml" />
+            </imports>
+
+            <!-- ... -->
+
+        </container>
 
     .. code-block:: php
 
@@ -104,11 +115,22 @@ configuration file:
     .. code-block:: xml
 
         <!-- app/config/config_dev.xml -->
-        <imports>
-            <import resource="config.xml" />
-        </imports>
+        <?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:webprofiler="http://symfony.com/schema/dic/webprofiler"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/webprofiler
+                http://symfony.com/schema/dic/webprofiler/webprofiler-1.0.xsd">
+
+            <imports>
+                <import resource="config.xml" />
+            </imports>
+
+            <webprofiler:config toolbar="true" />
 
-        <webprofiler:config toolbar="true" />
+        </container>
 
     .. code-block:: php
 
@@ -201,7 +223,18 @@ this code and changing the environment string.
 
         .. code-block:: xml
 
-            <doctrine:dbal logging="%kernel.debug%" />
+            <?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:doctrine="http://symfony.com/schema/dic/doctrine"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    http://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/doctrine
+                    http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+
+                <doctrine:dbal logging="%kernel.debug%" />
+
+            </container>
 
         .. code-block:: php
 
@@ -279,13 +312,24 @@ The best way to accomplish this is via a new environment called, for example,
     .. code-block:: xml
 
         <!-- app/config/config_benchmark.xml -->
-        <imports>
-            <import resource="config_prod.xml" />
-        </imports>
-
-        <framework:config>
-            <framework:profiler only-exceptions="false" />
-        </framework:config>
+        <?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:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <imports>
+                <import resource="config_prod.xml" />
+            </imports>
+
+            <framework:config>
+                <framework:profiler only-exceptions="false" />
+            </framework:config>
+
+        </container>
 
     .. code-block:: php
 

configuration/environments.rst

@@ -37,14 +37,22 @@ variable in your service container configuration, you can reference it using
     .. code-block:: xml
 
         <!-- app/config/config.xml -->
-        <!-- xmlns:doctrine="http://symfony.com/schema/dic/doctrine" -->
-        <!-- xsi:schemaLocation="http://symfony.com/schema/dic/doctrine http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd"> -->
+        <?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:doctrine="http://symfony.com/schema/dic/doctrine"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/doctrine
+                http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
 
-        <doctrine:config>
-            <doctrine:dbal
-                host="%env(DATABASE_HOST)%"
-            />
-        </doctrine:config>
+            <doctrine:config>
+                <doctrine:dbal
+                    host="%env(DATABASE_HOST)%"
+                />
+            </doctrine:config>
+
+        </container>
 
     .. code-block:: php
 
@@ -145,9 +153,17 @@ in the container. The following imports a file named ``parameters.php``.
     .. code-block:: xml
 
         <!-- app/config/config.xml -->
-        <imports>
-            <import resource="parameters.php" />
-        </imports>
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <imports>
+                <import resource="parameters.php" />
+            </imports>
+
+        </container>
 
     .. code-block:: php
 

configuration/external_parameters.rst

@@ -121,6 +121,7 @@ define your own templates directory (or directories):
             <twig:config>
                 <twig:path>%kernel.root_dir%/../templates</twig:path>
             </twig:config>
+
         </container>
 
     .. code-block:: php
@@ -197,6 +198,7 @@ You also need to change the ``extra.symfony-web-dir`` option in the
 
                 <!-- ... -->
                 <assetic:config read-from="%kernel.root_dir%/../../public_html" />
+
             </container>
 
         .. code-block:: php

configuration/override_dir_structure.rst

@@ -56,10 +56,10 @@ Now, examine the results to see this closely:
             <my-bundle:config logging="true" />
             <!-- true, as expected -->
 
-             <my-bundle:config logging="%kernel.debug%" />
-             <!-- true/false (depends on 2nd parameter of AppKernel),
-                  as expected, because %kernel.debug% inside configuration
-                  gets evaluated before being passed to the extension -->
+            <my-bundle:config logging="%kernel.debug%" />
+            <!-- true/false (depends on 2nd parameter of AppKernel),
+                 as expected, because %kernel.debug% inside configuration
+                 gets evaluated before being passed to the extension -->
 
             <my-bundle:config />
             <!-- passes the string "%kernel.debug%".