Workflow

In applications using Symfony Flex, run this command toinstall the workflow feature before using it:

Configuration

To see all configuration options, if you are using the component inside aSymfony project run this command:

$ php bin/console config:dump-reference framework workflows

A workflow is a process or a lifecycle that your objects go through. Eachstep or stage in the process is called a place. You do also define _transitions_to that describes the action to get from one place to another.

A set of places and transitions creates a definition. A workflow needsa and a way to write the states to the objects (i.e. aninstance of a MarkingStoreInterface.)

Consider the following example for a blog post. A post can have these places:draft, reviewed, rejected, published. You can define the workflowlike this:

• YAML

# config/framework.yaml
framework:
    workflows:
        blog_publishing:
            type: 'workflow' # or 'state_machine'
            audit_trail:
                enabled: true
            marking_store:
                type: 'method'
                property: 'currentPlace'
            supports:
                - App\Entity\BlogPost
            initial_marking: draft
            places:
                - draft
                - reviewed
                - rejected
                - published
            transitions:
                to_review:
                    from: draft
                    to:   reviewed
                publish:
                    from: reviewed
                    to:   published
                reject:
                    from: reviewed
                    to:   rejected

• XML

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
>
 
    <framework:config>
        <framework:workflow name="blog_publishing" type="workflow">
            <framework:audit-trail enabled="true"/>
            <framework:marking-store type="single_state">
                <framework:argument>currentPlace</framework:argument>
            </framework:marking-store>
            <framework:support>App\Entity\BlogPost</framework:support>
            <framework:initial-marking>draft</framework:initial-marking>
            <framework:place>draft</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>reviewed</framework:to>
            </framework:transition>
            <framework:transition name="publish">
                <framework:from>reviewed</framework:from>
                <framework:to>published</framework:to>
            </framework:transition>
            <framework:transition name="reject">
                <framework:from>reviewed</framework:from>
                <framework:to>rejected</framework:to>
            </framework:transition>
        </framework:workflow>
    </framework:config>
</container>

• PHP

// app/config/config.php
$container->loadFromExtension('framework', [
    // ...
    'workflows' => [
        'blog_publishing' => [
            'type' => 'workflow', // or 'state_machine'
            'audit_trail' => [
                'enabled' => true
            ],
            'marking_store' => [
                'type' => 'method'
                'property' => ['currentPlace']
            ],
            'supports' => ['App\Entity\BlogPost'],
            'initial_marking' => 'draft',
            'places' => [
                'draft',
                'reviewed',
                'rejected',
                'published',
            ],
            'transitions' => [
                'to_review' => [
                    'from' => 'draft',
                    'to' => 'reviewed',
                ],
                'publish' => [
                    'from' => 'reviewed',
                    'to' => 'published',
                ],
                'reject' => [
                    'from' => 'reviewed',
                    'to' => 'rejected',
                ],
            ],
        ],
    ],
]);

Tip

If you are creating your first workflows, consider using the workflow:dumpcommand to .

As configured, the following property is used by the marking store:

class BlogPost
{
    // This property is used by the marking store
    public $currentPlace;
    public $title;
    public $content;
}

Note

The marking store type could be "multiple_state" or "single_state". A singlestate marking store does not support a model being on multiple places at thesame time. This means a "workflow" must use a "multiple_state" marking storeand a "state_machine" must use a "single_state" marking store. Symfonyconfigures the marking store according to the "type" by default, so it'spreferable to not configure it.

A single state marking store uses a string to store the data. A multiplestate marking store uses an array to store the data.

Tip

The marking_store.type (the default value depends on the type value)and arguments (default value ['marking']) attributes of themarking_store option are optional. If omitted, their default values willbe used. It's highly recommenced to use the default value.

Tip

Setting the audit_trail.enabled option to true makes the applicationgenerate detailed log messages for the workflow activity.

Using Events

To make your workflows more flexible, you can construct the Workflowobject with an EventDispatcher. You can now create event listeners toblock transitions (i.e. depending on the data in the blog post) and doadditional actions when a workflow operation happened (e.g. sendingannouncements).

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 followingorder:

• workflow.guard

• Validate whether the transition is blocked or not (see andblocking 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.[workflow name].transition
• workflow.[workflow name].transition.[transition name]
  • workflow.enter
  • The subject is about to enter a new place. This event is triggered justbefore the subject places are updated, which means that the marking of thesubject is not yet updated with the new places.

The three events being dispatched are:

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

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]

Note

The leaving and entering events are triggered even for transitions that stayin same place.

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

use Psr\Log\LoggerInterface;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Workflow\Event\Event;
 
class WorkflowLogger implements EventSubscriberInterface
{
    private $logger;
 
    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',
        ];
    }
}

There are a special kind of events called "Guard events". Their event listenersare invoked every time a call to Workflow::can, Workflow::apply orWorkflow::getEnabledTransitions is executed. With the guard events you mayadd custom logic to decide which transitions should be blocked or not. Here is alist of the guard event names.

• workflow.guard
• workflow.[workflow name].guard
• workflow.[workflow name].guard.[transition name]This example stops any blog post being transitioned to "reviewed" if it ismissing a title:

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Workflow\Event\GuardEvent;
 
class BlogPostReviewListener implements EventSubscriberInterface
{
    public function guardReview(GuardEvent $event)
    {
        /** @var App\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'],
        ];
    }
}

Event Methods

Each workflow event is an instance of Event.This means that each event has access to the following information:

• Returns the of the workflow.
• getSubject()
• Returns the object that dispatches the event.
• Returns the Transition that dispatches the event.
• Returns a string with the name of the workflow that triggered the event.
• getMetadata()
• Returns if transition is blocked.
• setBlocked()
• Sets the blocked value.
• Returns the event TransitionBlockerList.See .
• addTransitionBlocker()
• Add a instance.

The execution of the workflow can be controlled by executing custom logic todecide if the current transition is blocked or allowed before applying it. Thisfeature 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 thetransition. The value of this option is any valid expression created with the:

# 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", "is_valid"
                    guard: "is_authenticated"
                    from: reviewed
                    to:   published
                reject:
                    # or any valid expression language with "subject" referring to the supported object
                    guard: "has_role('ROLE_ADMIN') and subject.isRejectable()"
                    from: reviewed
                    to:   rejected

You can also use transition blockers to block and return a user-friendly errormessage when you stop a transition from happening.In the example we get this message from theEvent's metadata, giving you acentral place to manage the text.

This example has been simplified; in production you may prefer to use the component to manage messages in oneplace:

namespace App\Listener\Workflow\Task;
 
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Workflow\Event\GuardEvent;
use Symfony\Component\Workflow\TransitionBlocker;
 
class BlogPostPublishListener implements EventSubscriberInterface
{
    public function guardPublish(GuardEvent $event)
    {
        $eventTransition = $event->getTransition();
        $hourLimit = $event->getMetadata('hour_limit', $eventTransition);
 
        if (date('H') <= $hourLimit) {
            return;
        }
 
        // Block the transition "publish" if it is more than 8 PM
        // with the message for end user
        $explanation = $event->getMetadata('explanation', $eventTransition);
        $event->addTransitionBlocker(new TransitionBlocker($explanation , 0));
    }
 
    public static function getSubscribedEvents()
    {
        return [
            'workflow.blog_publishing.guard.publish' => ['guardPublish'],
        ];
    }
}

New in version 4.1: The transition blockers were introduced in Symfony 4.1.

Usage in Twig

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

• workflow_can()
• Returns true if the given object can make the given transition.
• workflow_transitions()
• 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:

<h3>Actions on Blog Post</h3>
{% if workflow_can(post, 'publish') %}
    <a href="...">Publish</a>
{% endif %}
{% if workflow_can(post, 'to_review') %}
    <a href="...">Submit to review</a>
{% endif %}
{% if workflow_can(post, 'reject') %}
    <a href="...">Reject</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 'reviewed' in workflow_marked_places(post) %}
    <span class="label">Reviewed</span>
{% endif %}

New in version 4.1: The feature to store metadata in workflows was introduced in Symfony 4.1.

In case you need it, you can store arbitrary metadata in workflows, theirplaces, and their transitions using the metadata option. This metadata canbe as simple as the title of the workflow or as complex as your own applicationrequires:

• YAML

• XML

<!-- config/packages/workflow.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
>
    <framework:config>
        <framework:workflow name="blog_publishing">
            <framework:metadata>
                <framework:title>Blog Publishing Workflow</framework:title>
            </framework:metadata>
            <!-- ... -->
            <framework:place name="draft">
                <framework:metadata>
                    <framework:max-num-of-words>500</framework:max-num-of-words>
                </framework:metadata>
            </framework:place>
            <!-- ... -->
            <framework:transition name="to_review">
                <framework:from>draft</framework:from>
                <framework:to>review</framework:to>
                <framework:metadata>
                    <framework:priority>0.5</framework:priority>
                </framework:metadata>
            </framework:transition>
            <framework:transition name="publish">
                <framework:from>reviewed</framework:from>
                <framework:to>published</framework:to>
                <framework:metadata>
                    <framework:hour_limit>20</framework:hour_limit>
                    <framework:explanation>You can not publish after 8 PM.</framework:explanation>
                </framework:metadata>
            </framework:transition>
        </framework:workflow>
    </framework:config>
</container>

• PHP

// config/packages/workflow.php
$container->loadFromExtension('framework', [
    // ...
    'workflows' => [
        'blog_publishing' => [
            'metadata' => [
                'title' => 'Blog Publishing Workflow',
            ],
            // ...
            'places' => [
                'draft' => [
                    'metadata' => [
                        'max_num_of_words' => 500,
                    ],
                ],
                // ...
            ],
            'transitions' => [
                'to_review' => [
                    'from' => 'draft',
                    'to' => 'review',
                    'metadata' => [
                        'priority' => 0.5,
                    ],
                ],
                'publish' => [
                    'from' => 'reviewed',
                    'to' => 'published',
                    'metadata' => [
                        'hour_limit' => 20,
                        'explanation' => 'You can not publish after 8 PM.',
                    ],
                ],
            ],
        ],
    ],
]);

Then you can access this metadata in your controller as follows:

use App\Entity\BlogPost;
use Symfony\Component\Workflow\Registry;
 
public function myController(Registry $registry, BlogPost $post)
{
    $workflow = $registry->get($post);
 
    $title = $workflow
        ->getMetadataStore()
        ->getWorkflowMetadata()['title'] ?? 'Default title'
    ;
 
    $maxNumOfWords = $workflow
        ->getMetadataStore()
        ->getPlaceMetadata('draft')['max_num_of_words'] ?? 500
    ;
 
    $aTransition = $workflow->getDefinition()->getTransitions()[0];
    $priority = $workflow
        ->getMetadataStore()
        ->getTransitionMetadata($aTransition)['priority'] ?? 0
    ;
}

There is a getMetadata() method that works with all kinds of metadata:

// pass no arguments to getMetadata() to get "workflow metadata"
$title = $workflow->getMetadataStore()->getMetadata()['title'];
 
// pass a string (the place name) to getMetadata() to get "place metadata"
$maxNumOfWords = $workflow->getMetadataStore()->getMetadata('draft')['max_num_of_words'];
 
// pass a Transition object to getMetadata() to get "transition metadata"
$priority = $workflow->getMetadataStore()->getMetadata($aTransition)['priority'];

In a in your controller:

// $transition = ...; (an instance of Transition)
 
// $workflow is a Workflow instance retrieved from the Registry (see above)
$title = $workflow->getMetadataStore()->getMetadata('title', $transition);
$this->addFlash('info', "You have successfully applied the transition with title: '$title'");

Metadata can also be accessed in a Listener, from the Event object.

Learn more

• How to Dump Workflows