Workflow

Workflow

Using the Workflow component inside a Symfony application requires to know firstsome basic theory and concepts about workflows and state machines.Read this article for a quick overview.

Installation

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

$ composer require symfony/workflow

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

Creating a Workflow

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 Definition 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 debug the workflow contents.

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.

With this workflow named blog_publishing, you can get help to decidewhat actions are allowed on a blog post:

use App\Entity\BlogPost;
use Symfony\Component\Workflow\Exception\LogicException;
 
$post = new BlogPost();
 
$workflow = $this->container->get('workflow.blog_publishing');
$workflow->can($post, 'publish'); // False
$workflow->can($post, 'to_review'); // True
 
// Update the currentState on the post
try {
    $workflow->apply($post, 'to_review');
} catch (LogicException $exception) {
    // ...
}
 
// See all the available transitions for the post in the current state
$transitions = $workflow->getEnabledTransitions($post);

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 (seeguard events andblocking transitions).