Workflow Guard documentation

Author: noniagriconomie

workflow/usage.rst

@@ -327,7 +327,7 @@ 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 (:ref:`see below <workflow-usage-guard-events>` and :ref:`using guards <workflow-usage-using-guards>`).
 
     The three events being dispatched are:
 
@@ -439,7 +439,7 @@ 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 what transitions should be blocked or not. Here is a list
 of the guard event names.
 
 * ``workflow.guard``
@@ -460,8 +460,8 @@ 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 defined
                 $event->setBlocked(true);
             }
         }
@@ -501,6 +501,48 @@ This class has two more methods:
 :method:`Symfony\\Component\\Workflow\\Event\\GuardEvent::setBlocked`
     Sets the blocked value.
 
+.. _workflow-usage-using-guards:
+
+Using Guards
+------------
+
+The component has a guard logic to control the execution of your workflow on top of your configuration.
+
+It allows you to execute your custom logic to decide if the transition is blocked or not, before actually
+applying this transition.
+
+You have multiple optional ways to use guards in your workflow.
+
+The first way is :ref:`with the guard event <workflow-usage-guard-events>`, which allows you to implement
+any desired feature.
+
+Another one is via the configuration and its specific entry `guard` on a transition.
+
+This `guard` entry allows any expression that is valid for the Expression Language component:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/workflow.yaml
+        framework:
+            workflows:
+                blog_publishing:
+                    # previous configuration
+                    transitions:
+                        to_review:
+                            guard: "is_granted('ROLE_REVIEWER')" # the transition is allowed only if the current user has the ROLE_REVIEWER role.
+                            from: draft
+                            to:   review
+                        publish:
+                            guard: "is_authenticated" # or "is_anonymous", "is_remember_me", "is_fully_authenticated", "is_granted"
+                            from: review
+                            to:   published
+                        reject:
+                            guard: "has_role("ROLE_ADMIN") and subject.isStatusReview() and " # or any valid expression language
+                            from: review
+                            to:   rejected
+
 Usage in Twig
 -------------