@@ -327,7 +327,7 @@ When a state transition is initiated, the events are dispatched in the following
327327order:
328328
329329``workflow.guard ``
330- Validate whether the transition isallowed at all (:ref: `see below <workflow-usage-guard-events >`).
330+ Validate whether the transition isblocked or not (:ref: `see below <workflow-usage-guard-events >` and :ref: ` using guards < workflow-usage-using-guards >`).
331331
332332 The three events being dispatched are:
333333
@@ -439,7 +439,7 @@ Guard Events
439439There are a special kind of events called "Guard events". Their event listeners
440440are invoked every time a call to ``Workflow::can ``, ``Workflow::apply `` or
441441``Workflow::getEnabledTransitions `` is executed. With the guard events you may
442- add custom logic to decide what transitionsare valid or not. Here is a list
442+ add custom logic to decide what transitionsshould be blocked not. Here is a list
443443of the guard event names.
444444
445445* ``workflow.guard ``
@@ -460,8 +460,8 @@ See example to make sure no blog post without title is moved to "review"::
460460 $title = $post->title;
461461
462462 if (empty($title)) {
463- //Posts without title are not allowed
464- //to perform thetransition "to_review"
463+ //Block the transition "to_review"
464+ //if thepost has no title
465465 $event->setBlocked(true);
466466 }
467467 }
@@ -501,6 +501,48 @@ This class has two more methods:
501501:method: `Symfony\\ Component\\ Workflow\\ Event\\ GuardEvent::setBlocked `
502502 Sets the blocked value.
503503
504+ .. _workflow-usage-using-guards :
505+
506+ Using Guards
507+ ------------
508+
509+ The component has a guard logic to control the execution of your workflow on top of your configuration.
510+
511+ It allows you to execute your custom logic to decide if the transition is blocked or not, before actually
512+ applying this transition.
513+
514+ You have multiple optional ways to use guards in your workflow.
515+
516+ The first way is:ref: `with the guard event <workflow-usage-guard-events >`, which allows you to implement
517+ any desired feature.
518+
519+ Another one is via the configuration and its specific entry `guard ` on a transition.
520+
521+ This `guard ` entry allows any expression that is valid for the Expression Language component:
522+
523+ ..configuration-block ::
524+
525+ ..code-block ::yaml
526+
527+ # config/packages/workflow.yaml
528+ framework :
529+ workflows :
530+ blog_publishing :
531+ # previous configuration
532+ transitions :
533+ to_review :
534+ guard :" is_granted('ROLE_REVIEWER')" # the transition is allowed only if the current user has the ROLE_REVIEWER role.
535+ from :draft
536+ to :review
537+ publish :
538+ guard :" is_authenticated" # or "is_anonymous", "is_remember_me", "is_fully_authenticated", "is_granted"
539+ from :review
540+ to :published
541+ reject :
542+ guard :" has_role(" ROLE_ADMIN") and subject.isStatusReview() and " # or any valid expression language
543+ from :review
544+ to :rejected
545+
504546 Usage in Twig
505547-------------
506548