Merge branch '3.4'

* 3.4: (40 commits)
  Adding an article to explain the 3.3 changes, and how to upgrade
  updating instance
  Avoid backticks in shell scripts
  Update optional_dependencies.rst
  Fix xml blocks
  pass only strings to loadUserByUsername()
  Fix Authenticator Class (getCredentials) example
  Documented addAnnotatedClassesToCompile() and the use of class patterns
  Added the picture that shows how GuardAuthenticationListener calls Authentication Guard methods.
  [#7205] minor tweak
  Simplified the use of transChoice()
  [#7875] minor tweaks
  Minor fix
  Minor changes
  Properly show all events and describe guard events
  [#7891] remove not needed sentence
  [#7773] fix line length
  Add helpful remarks on custom DataCollector
  Remove use of deprecated security.exception_listener.class parameter
  Update resources.rst
  ...

Author: weaverryan

_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

@@ -133,9 +133,14 @@ Symfony creates a big ``classes.php`` file in the cache directory to aggregate
 the contents of the PHP classes that are used in every request. This reduces the
 I/O operations and increases the application performance.
 
+.. versionadded:: 3.2
+   The ``addAnnotatedClassesToCompile()`` method was added in Symfony 3.2.
+
 Your bundles can also add their own classes into this file thanks to the
-``addClassesToCompile()`` method. Define the classes to compile as an array of
-their fully qualified class names::
+``addClassesToCompile()`` and ``addAnnotatedClassesToCompile()`` methods (both
+work in the same way, but the second one is for classes that contain PHP
+annotations). Define the classes to compile as an array of their fully qualified
+class names::
 
     use AppBundle\Manager\UserManager;
     use AppBundle\Utils\Slugger;
@@ -145,22 +150,52 @@ their fully qualified class names::
     {
         // ...
 
+        // this method can't compile classes that contain PHP annotations
         $this->addClassesToCompile(array(
             UserManager::class,
             Slugger::class,
             // ...
         ));
+
+        // add here only classes that contain PHP annotations
+        $this->addAnnotatedClassesToCompile(array(
+            'AppBundle\\Controller\\DefaultController',
+            // ...
+        ));
     }
 
 .. note::
 
     If some class extends from other classes, all its parents are automatically
     included in the list of classes to compile.
 
-Beware that this technique **can't be used in some cases**:
+.. versionadded:: 3.2
+   The option to add classes to compile using patterns was introduced in Symfony 3.2.
+
+The classes to compile can also be added using file path patterns::
+
+    // ...
+    public function load(array $configs, ContainerBuilder $container)
+    {
+        // ...
+
+        $this->addClassesToCompile(array(
+            '**Bundle\\Manager\\',
+            // ...
+        ));
+
+        $this->addAnnotatedClassesToCompile(array(
+            '**Bundle\\Controller\\',
+            // ...
+        ));
+    }
+
+Patterns are transformed into the actual class namespaces using the classmap
+generated by Composer. Therefore, before using these patterns, you must generate
+the full classmap executing the ``dump-autoload`` command of Composer.
+
+.. caution::
 
-* When classes contain annotations, such as controllers with ``@Route``
-  annotations and entities with ``@ORM`` or ``@Assert`` annotations, because
-  the file location retrieved from PHP reflection changes;
-* When classes use the ``__DIR__`` and ``__FILE__`` constants, because their
-  values will change when loading these classes from the ``classes.php`` file.
+    This technique can't be used when the classes to compile use the ``__DIR__``
+    or ``__FILE__`` constants, because their values will change when loading
+    these classes from the ``classes.php`` file.

bundles/extension.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

@@ -112,6 +112,12 @@ Caching
 The component provides some different caching strategies, read more about them
 in :doc:`/components/expression_language/caching`.
 
+AST Dumping and Editing
+-----------------------
+
+The AST (*Abstract Syntax Tree*) of expressions can be dumped and manipulated
+as explained in :doc:`/components/expression_language/ast`.
+
 Learn More
 ----------
 

components/expression_language.rst

@@ -0,0 +1,49 @@
+.. index::
+    single: AST; ExpressionLanguage
+    single: AST; Abstract Syntax Tree
+
+Dumping and Manipulating the AST of Expressions
+===============================================
+
+Manipulating or inspecting the expressions created with the ExpressionLanguage
+component is difficult because they are plain strings. A better approach is to
+turn those expressions into an AST. In computer science, `AST`_ (*Abstract
+Syntax Tree*) is *"a tree representation of the structure of source code written
+in a programming language"*. In Symfony, a ExpressionLanguage AST is a set of
+nodes that contain PHP classes representing the given expression.
+
+Dumping the AST
+---------------
+
+Call the :method:`Symfony\\Component\\ExpressionLanguage\\ExpressionLanguage::getNodes`
+method after parsing any expression to get its AST::
+
+    use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
+
+    $ast = (new ExpressionLanguage())
+        ->parse('1 + 2')
+        ->getNodes()
+    ;
+
+    // dump the AST nodes for inspection
+    var_dump($ast);
+
+    // dump the AST nodes as a string representation
+    $astAsString = $ast->dump();
+
+Manipulating the AST
+--------------------
+
+The nodes of the AST can also be dumped into a PHP array of nodes to allow
+manipulating them. Call the :method:`Symfony\\Component\\ExpressionLanguage\\ExpressionLanguage::toArray`
+method to turn the AST into an array::
+
+    // ...
+
+    $astAsArray = (new ExpressionLanguage())
+        ->parse('1 + 2')
+        ->getNodes()
+        ->toArray()
+    ;
+
+.. _`AST`: https://en.wikipedia.org/wiki/Abstract_syntax_tree

components/expression_language/ast.rst

@@ -544,7 +544,7 @@ handling, switching to chunked encoding instead::
 
     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

@@ -253,16 +253,39 @@ all the forms as a string separated by a pipe (``|``)::
 To translate pluralized messages, use the
 :method:`Symfony\\Component\\Translation\\Translator::transChoice` method::
 
+    // the %count% placeholder is assigned to the second argument...
     $translator->transChoice(
         'There is one apple|There are %count% apples',
+        10
+    );
+
+    // ...but you can define more placeholders if needed
+    $translator->transChoice(
+        'Hurry up %name%! There is one apple left.|There are %count% apples left.',
         10,
-        array('%count%' => 10)
+        // no need to include %count% here; Symfony does that for you
+        array('%name%' => $user->getName())
     );
 
 The second argument (``10`` in this example) is the *number* of objects being
 described and is used to determine which translation to use and also to populate
 the ``%count%`` placeholder.
 
+.. versionadded:: 3.2
+
+    Before Symfony 3.2, the placeholder used to select the plural (``%count%``
+    in this example) must be included in the third optional argument of the
+    ``transChoice()`` method::
+
+        $translator->transChoice(
+            'There is one apple|There are %count% apples',
+            10,
+            array('%count%' => 10)
+        );
+
+    Starting from Symfony 3.2, when the only placeholder is ``%count%``, you
+    don't have to pass this third argument.
+
 Based on the given number, the translator chooses the right plural form.
 In English, most words have a singular form when there is exactly one object
 and a plural form for all other numbers (0, 2, 3...). So, if ``count`` is
@@ -366,11 +389,25 @@ use for translation::
     $translator->transChoice(
         '{0} There are no apples|{1} There is one apple|]1,Inf[ There are %count% apples',
         10,
-        array('%count%' => 10),
+        array(),
         'messages',
         'fr_FR'
     );
 
+.. note::
+
+    Starting from Symfony 3.2, the third argument of ``transChoice()`` is
+    optional when the only placeholder in use is ``%count%``. In previous
+    Symfony versions you needed to always define it::
+
+        $translator->transChoice(
+            '{0} There are no apples|{1} There is one apple|]1,Inf[ There are %count% apples',
+            10,
+            array('%count%' => 10),
+            'messages',
+            'fr_FR'
+        );
+
 Retrieving the Message Catalogue
 --------------------------------
 

components/translation/usage.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,
             )));