Using Events¶

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) 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.

When a state transition is initiated, the events are dispatched in the following order:

workflow.guard

Validate whether the transition is blocked or not (see guard events and blocking transitions).

The three events being dispatched are:

• workflow.guard
• workflow.[workflow name].guard
• workflow.[workflow name].guard.[transition name]

workflow.leave

The subject is about to leave a place.

The three events being dispatched are:

• workflow.leave
• workflow.[workflow name].leave
• workflow.[workflow name].leave.[place name]

workflow.transition

The subject is going through this transition.

The three events being dispatched are:

• workflow.transition
• workflow.[workflow name].transition
• workflow.[workflow name].transition.[transition name]

workflow.enter

The subject is about to enter a new place. This event is triggered just before the subject places are updated, which means that the marking of the subject is not yet updated with the new places.

The three events being dispatched are:

• workflow.enter
• workflow.[workflow name].enter
• workflow.[workflow name].enter.[place name]

workflow.entered

The subject has entered in the places and the marking is updated (making it a good place to flush data in Doctrine).

The three events being dispatched are:

• workflow.entered
• workflow.[workflow name].entered
• workflow.[workflow name].entered.[place name]

workflow.completed

The object has completed this transition.

The three events being dispatched are:

• workflow.completed
• workflow.[workflow name].completed
• workflow.[workflow name].completed.[transition name]

workflow.announce

Triggered for each transition that now is accessible for the subject.

The three events being dispatched are:

• workflow.announce
• workflow.[workflow name].announce
• workflow.[workflow name].announce.[transition name]

Here is an example of how to enable logging for every time a "blog_publishing" workflow leaves a place:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

use Psr\Log\LoggerInterface;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Workflow\Event\Event;

class WorkflowLogger implements EventSubscriberInterface
{
    public function __construct(LoggerInterface $logger)
    {
        $this->logger = $logger;
    }

    public function onLeave(Event $event)
    {
        $this->logger->alert(sprintf(
            'Blog post (id: "%s") performed transition "%s" from "%s" to "%s"',
            $event->getSubject()->getId(),
            $event->getTransition()->getName(),
            implode(', ', array_keys($event->getMarking()->getPlaces())),
            implode(', ', $event->getTransition()->getTos())
        ));
    }

    public static function getSubscribedEvents()
    {
        return [
            'workflow.blog_publishing.leave' => 'onLeave',
        ];
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

use Symfony\Component\Workflow\Event\GuardEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class BlogPostReviewListener implements EventSubscriberInterface
{
    public function guardReview(GuardEvent $event)
    {
        /** @var AppBundle\Entity\BlogPost $post */
        $post = $event->getSubject();
        $title = $post->title;

        if (empty($title)) {
            // Block the transition "to_review" if the post has no title
            $event->setBlocked(true);
        }
    }

    public static function getSubscribedEvents()
    {
        return [
            'workflow.blog_publishing.guard.to_review' => ['guardReview'],
        ];
    }
}

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 the 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 ExpressionLanguage component:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

# 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¶

Symfony defines several Twig functions to manage workflows and reduce the need of domain logic in your templates:

workflow_can()

Returns true if the given object can make the given transition.

workflow_transitions()

Returns an array with all the transitions enabled for the given object.

workflow_marked_places()

Returns an array with the place names of the given marking.

workflow_has_marked_place()

Returns true if the marking of the given object has the given state.

The following example shows these functions in action:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

<h3>Actions</h3>
{% if workflow_can(post, 'publish') %}
    <a href="...">Publish article</a>
{% endif %}
{% if workflow_can(post, 'to_review') %}
    <a href="...">Submit to review</a>
{% endif %}
{% if workflow_can(post, 'reject') %}
    <a href="...">Reject article</a>
{% endif %}

{# Or loop through the enabled transitions #}
{% for transition in workflow_transitions(post) %}
    <a href="...">{{ transition.name }}</a>
{% else %}
    No actions available.
{% endfor %}

{# Check if the object is in some specific place #}
{% if workflow_has_marked_place(post, 'reviewed') %}
    <p>This post is ready for review.</p>
{% endif %}

{# Check if some place has been marked on the object #}
{% if 'waiting_some_approval' in workflow_marked_places(post) %}
    <span class="label">PENDING</span>
{% endif %}

Learn more¶