Merge branch '3.4' into 4.2

* 3.4:
  [Workflow] Guard documentation

Author: javiereguiluz

workflow/usage.rst

@@ -27,8 +27,8 @@ A set of places and transitions creates a **definition**. A workflow needs
 a ``Definition`` and a way to write the states to the objects (i.e. an
 instance of a :class:`Symfony\\Component\\Workflow\\MarkingStore\\MarkingStoreInterface`.)
 
-Consider the following example for a blog post that can have these places:
-``draft``, ``review``, ``rejected``, ``published``. You can define the workflow
+Consider the following example for a blog post. A post can have these places:
+``draft``, ``reviewed``, ``rejected``, ``published``. You can define the workflow
 like this:
 
 .. configuration-block::
@@ -51,18 +51,18 @@ like this:
                     initial_place: draft
                     places:
                         - draft
-                        - review
+                        - reviewed
                         - rejected
                         - published
                     transitions:
                         to_review:
                             from: draft
-                            to:   review
+                            to:   reviewed
                         publish:
-                            from: review
+                            from: reviewed
                             to:   published
                         reject:
-                            from: review
+                            from: reviewed
                             to:   rejected
 
     .. code-block:: xml
@@ -87,24 +87,24 @@ like this:
                     <framework:support>App\Entity\BlogPost</framework:support>
 
                     <framework:place>draft</framework:place>
-                    <framework:place>review</framework:place>
+                    <framework:place>reviewed</framework:place>
                     <framework:place>rejected</framework:place>
                     <framework:place>published</framework:place>
 
                     <framework:transition name="to_review">
                         <framework:from>draft</framework:from>
 
-                        <framework:to>review</framework:to>
+                        <framework:to>reviewed</framework:to>
                     </framework:transition>
 
                     <framework:transition name="publish">
-                        <framework:from>review</framework:from>
+                        <framework:from>reviewed</framework:from>
 
                         <framework:to>published</framework:to>
                     </framework:transition>
 
                     <framework:transition name="reject">
-                        <framework:from>review</framework:from>
+                        <framework:from>reviewed</framework:from>
 
                         <framework:to>rejected</framework:to>
                     </framework:transition>
@@ -132,21 +132,21 @@ like this:
                     'supports' => ['App\Entity\BlogPost'],
                     'places' => [
                         'draft',
-                        'review',
+                        'reviewed',
                         'rejected',
                         'published',
                     ],
                     'transitions' => [
                         'to_review' => [
                             'from' => 'draft',
-                            'to' => 'review',
+                            'to' => 'reviewed',
                         ],
                         'publish' => [
-                            'from' => 'review',
+                            'from' => 'reviewed',
                             'to' => 'published',
                         ],
                         'reject' => [
-                            'from' => 'review',
+                            'from' => 'reviewed',
                             'to' => 'rejected',
                         ],
                     ],
@@ -244,7 +244,9 @@ When a state transition is initiated, the events are dispatched in the following
 order:
 
 ``workflow.guard``
-    Validate whether the transition is allowed at all (:ref:`see below <workflow-usage-guard-events>`).
+    Validate whether the transition is blocked or not (see
+    :ref:`guard events <workflow-usage-guard-events>` and
+    :ref:`blocking transitions <workflow-blocking-transitions>`).
 
     The three events being dispatched are:
 
@@ -356,14 +358,15 @@ Guard Events
 There are a special kind of events called "Guard events". Their event listeners
 are invoked every time a call to ``Workflow::can``, ``Workflow::apply`` or
 ``Workflow::getEnabledTransitions`` is executed. With the guard events you may
-add custom logic to decide what transitions are valid or not. Here is a list
+add custom logic to decide which transitions should be blocked or not. Here is a list
 of the guard event names.
 
 * ``workflow.guard``
 * ``workflow.[workflow name].guard``
 * ``workflow.[workflow name].guard.[transition name]``
 
-See example to make sure no blog post without title is moved to "review"::
+This example stops any blog post being transitioned to "reviewed" if it is
+missing a title::
 
     use Symfony\Component\Workflow\Event\GuardEvent;
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
@@ -377,8 +380,7 @@ See example to make sure no blog post without title is moved to "review"::
             $title = $post->title;
 
             if (empty($title)) {
-                // Posts without title are not allowed
-                // to perform the transition "to_review"
+                // Block the transition "to_review" if the post has no title
                 $event->setBlocked(true);
             }
         }
@@ -418,6 +420,46 @@ This class has two more methods:
 :method:`Symfony\\Component\\Workflow\\Event\\GuardEvent::setBlocked`
     Sets the blocked value.
 
+.. _workflow-blocking-transitions:
+
+Blocking Transitions
+--------------------
+
+The execution of the workflow can be controlled by executing custom logic to
+decide if the current transition is blocked or allowed before applying it. This
+feature is provided by "guards", which can be used in two ways.
+
+First, you can listen to :ref:`the guard events <workflow-usage-guard-events>`.
+Alternatively, you can define a ``guard`` configuration option for the
+transition. The value of this option is any valid expression created with the
+:doc:`ExpressionLanguage component </components/expression_language>`:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/workflow.yaml
+        framework:
+            workflows:
+                blog_publishing:
+                    # previous configuration
+                    transitions:
+                        to_review:
+                            # the transition is allowed only if the current user has the ROLE_REVIEWER role.
+                            guard: "is_granted('ROLE_REVIEWER')"
+                            from: draft
+                            to:   reviewed
+                        publish:
+                            # or "is_anonymous", "is_remember_me", "is_fully_authenticated", "is_granted"
+                            guard: "is_authenticated"
+                            from: reviewed
+                            to:   published
+                        reject:
+                            # or any valid expression language with "subject" referring to the post
+                            guard: "has_role("ROLE_ADMIN") and subject.isStatusReviewed()"
+                            from: reviewed
+                            to:   rejected
+
 Usage in Twig
 -------------
 
@@ -459,7 +501,7 @@ The following example shows these functions in action:
     {% endfor %}
 
     {# Check if the object is in some specific place #}
-    {% if workflow_has_marked_place(post, 'review') %}
+    {% if workflow_has_marked_place(post, 'reviewed') %}
         <p>This post is ready for review.</p>
     {% endif %}