Merge branch '3.2' into 3.3

* 3.2:
  [symfony#8048] some minor tweaks
  [symfony#8013] revert wrong data provider change
  correct PHP code
  Added a missing <script> tag in an example
  clarify workflow events
  minor tweak
  Fix comment to be consistent with the example
  Reworded the article about slashes in routing placeholders
  Minor reword of code contribution standards

Author: xabbuh

contributing/code/standards.rst

@@ -186,7 +186,7 @@ Naming Conventions
 * Use camelCase, not underscores, for variable, function and method
   names, arguments;
 
-* Use underscores for option names and parameter names;
+* Use underscores for configuration options and parameters;
 
 * Use namespaces for all classes;
 

form/type_guesser.rst

@@ -136,7 +136,7 @@ With this knowledge, you can easily implement the ``guessType()`` method of the
             $phpdoc = $reflectionProperty->getDocComment();
 
             // parse the $phpdoc into an array like:
-            // array('type' => 'string', 'since' => '1.0')
+            // array('var' => 'string', 'since' => '1.0')
             $phpdocTags = ...;
 
             return $phpdocTags;

form/unit_testing.rst

@@ -191,7 +191,7 @@ allows you to return a list of extensions to register::
             $this->validator
                 ->method('validate')
                 ->will($this->returnValue(new ConstraintViolationList()));
-            $validator
+            $this->validator
                 ->method('getMetadataFor')
                 ->will($this->returnValue(new ClassMetadata(Form::class)));
 

routing/generate_url_javascript.rst

@@ -26,10 +26,12 @@ variables. The ``escape()`` function helps escape any non-JavaScript-safe values
 But if you *actually* need to generate routes in pure JavaScript, consider using
 the `FOSJsRoutingBundle`_. It makes the following possible:
 
-.. code-block:: javascript
+.. code-block:: html+twig
 
+    <script>
     var url = Routing.generate('blog_show', {
         'slug': 'my-blog-post'
     });
+    </script>
 
 .. _`FOSJsRoutingBundle`: https://github.com/FriendsOfSymfony/FOSJsRoutingBundle

routing/slash_in_parameter.rst

@@ -5,47 +5,47 @@ How to Allow a "/" Character in a Route Parameter
 =================================================
 
 Sometimes, you need to compose URLs with parameters that can contain a slash
-``/``. For example, take the classic ``/hello/{username}`` route. By default,
-``/hello/Fabien`` will match this route but not ``/hello/Fabien/Kris``. This
-is because Symfony uses this character as separator between route parts.
+``/``. For example, consider the ``/share/{token}`` route. If the ``token``
+value contains a ``/`` character this route won't match. This is because Symfony
+uses this character as separator between route parts.
 
-This guide covers how you can modify a route so that ``/hello/Fabien/Kris``
-matches the ``/hello/{username}`` route, where ``{username}`` equals ``Fabien/Kris``.
+This article explains how you can modify a route definition so that placeholders
+can contain the ``/`` character too.
 
 Configure the Route
 -------------------
 
-By default, the Symfony Routing component requires that the parameters
-match the following regex path: ``[^/]+``. This means that all characters
-are allowed except ``/``.
+By default, the Symfony Routing component requires that the parameters match
+the following regular expression: ``[^/]+``. This means that all characters are
+allowed except ``/``.
 
-You must explicitly allow ``/`` to be part of your parameter by specifying
-a more permissive regex path.
+You must explicitly allow ``/`` to be part of your placeholder by specifying
+a more permissive regular expression for it:
 
 .. configuration-block::
 
     .. code-block:: php-annotations
 
         use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
 
-        class DemoController
+        class DefaultController
         {
             /**
-             * @Route("/hello/{username}", name="_hello", requirements={"username"=".+"})
+             * @Route("/share/{token}", name="share", requirements={"token"=".+"})
              */
-            public function helloAction($username)
+            public function shareAction($token)
             {
                 // ...
             }
         }
 
     .. code-block:: yaml
 
-        _hello:
-            path:     /hello/{username}
-            defaults: { _controller: AppBundle:Demo:hello }
+        share:
+            path:     /share/{token}
+            defaults: { _controller: AppBundle:Default:share }
             requirements:
-                username: .+
+                token: .+
 
     .. code-block:: xml
 
@@ -55,9 +55,9 @@ a more permissive regex path.
             xsi:schemaLocation="http://symfony.com/schema/routing
                 http://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="_hello" path="/hello/{username}">
-                <default key="_controller">AppBundle:Demo:hello</default>
-                <requirement key="username">.+</requirement>
+            <route id="share" path="/share/{token}">
+                <default key="_controller">AppBundle:Default:share</default>
+                <requirement key="token">.+</requirement>
             </route>
         </routes>
 
@@ -67,12 +67,20 @@ a more permissive regex path.
         use Symfony\Component\Routing\Route;
 
         $collection = new RouteCollection();
-        $collection->add('_hello', new Route('/hello/{username}', array(
-            '_controller' => 'AppBundle:Demo:hello',
+        $collection->add('share', new Route('/share/{token}', array(
+            '_controller' => 'AppBundle:Default:share',
         ), array(
-            'username' => '.+',
+            'token' => '.+',
         )));
 
         return $collection;
 
-That's it! Now, the ``{username}`` parameter can contain the ``/`` character.
+That's it! Now, the ``{token}`` parameter can contain the ``/`` character.
+
+.. note::
+
+    If the route defines several placeholders and you apply this permissive
+    regular expression to all of them, the results won't be the expected. For
+    example, if the route definition is ``/share/{path}/{token}`` and both
+    ``path`` and ``token`` accept ``/``, then ``path`` will contain its contents
+    and the token, and ``token`` will be empty.

workflow/usage.rst

@@ -177,10 +177,23 @@ what actions are allowed on a blog post::
 Using Events
 ------------
 
-To make your workflows even more powerful you could construct the ``Workflow``
+To make your workflows more flexible, you can construct the ``Workflow``
 object with an ``EventDispatcher``. You can now create event listeners to
-block transitions (i.e. depending on the data in the blog post). The following
-events are dispatched:
+block transitions (i.e. depending on the data in the blog post) and do
+additional actions when a workflow operation happened (e.g. sending
+announcements).
+
+Each step has three events that are fired in order:
+
+* An event for every workflow;
+* An event for the workflow concerned;
+* An event for the workflow concerned with the specific transition or place name.
+
+The following events are dispatched:
+
+* ``workflow.guard``
+* ``workflow.[workflow name].guard``
+* ``workflow.[workflow name].guard.[transition name]``
 
 * ``workflow.leave``
 * ``workflow.[workflow name].leave``
@@ -202,6 +215,14 @@ events are dispatched:
 * ``workflow.[workflow name].announce``
 * ``workflow.[workflow name].announce.[transition name]``
 
+When a state transition is initiated, the events are fired in the following order:
+
+- guard: Validate whether the transition is allowed at all (:ref:`see below <workflow-usage-guard-events>`);
+- leave: The object is about to leave a place;
+- transition: The object is going through this transition;
+- enter: The object entered a new place. This is the first event where the object' is marked as being in the new place;
+- announce: Triggered once for each workflow that now is available for the object.
+
 Here is an example how to enable logging for every time a the "blog_publishing" workflow leaves a place::
 
     use Psr\Log\LoggerInterface;
@@ -234,6 +255,8 @@ Here is an example how to enable logging for every time a the "blog_publishing"
         }
     }
 
+.. _workflow-usage-guard-events:
+
 Guard events
 ~~~~~~~~~~~~