Workflow

Using the Workflow component inside a Symfony application requires to know first some basic theory and concepts about workflows and state machines. :doc:`Read this article </workflow/workflow-and-state-machine>` for a quick overview.

A workflow is a process or a lifecycle that your objects go through. Each step 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 needs a Definition and a way to write the states to the objects (i.e. an instance of a :class:`Symfony\\Component\\Workflow\\MarkingStore\\MarkingStoreInterface`.)

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

.. configuration-block::

    .. code-block:: yaml

        # app/config/config.yml
        framework:
            workflows:
                blog_publishing:
                    type: 'workflow' # or 'state_machine'
                    audit_trail:
                        enabled: true
                    marking_store:
                        type: 'multiple_state' # or 'single_state'
                        arguments:
                            - 'currentPlace'
                    supports:
                        - AppBundle\Entity\BlogPost
                    initial_place: draft
                    places:
                        - draft
                        - reviewed
                        - rejected
                        - published
                    transitions:
                        to_review:
                            from: draft
                            to:   reviewed
                        publish:
                            from: reviewed
                            to:   published
                        reject:
                            from: reviewed
                            to:   rejected

    .. code-block:: 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>AppBundle\Entity\BlogPost</framework:support>

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

    .. code-block:: php

        // app/config/config.php
        $container->loadFromExtension('framework', [
            // ...
            'workflows' => [
                'blog_publishing' => [
                    'type' => 'workflow', // or 'state_machine'
                    'audit_trail' => [
                        'enabled' => true
                    ],
                    'marking_store' => [
                        'type' => 'multiple_state', // or 'single_state'
                        'arguments' => ['currentPlace']
                    ],
                    'supports' => ['AppBundle\Entity\BlogPost'],
                    '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:dump command to :doc:`debug the workflow contents </workflow/dumping-workflows>`.

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 single state marking store does not support a model being on multiple places at the same time. This means a "workflow" must use a "multiple_state" marking store and a "state_machine" must use a "single_state" marking store. Symfony configures the marking store according to the "type" by default, so it's preferable to not configure it.

A single state marking store uses a string to store the data. A multiple state 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 the marking_store option are optional. If omitted, their default values will be used. It's highly recommenced to use the default value.

Tip

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

.. versionadded:: 3.3

    The ``audit_trail`` option was introduced in Symfony 3.3.

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

$post = new AppBundle\Entity\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 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 :ref:`guard events <workflow-usage-guard-events>` and :ref:`blocking transitions <workflow-blocking-transitions>`).