.. index::
    single: Workflow; Usage

How to Create and Use Workflows

Installation

In applications using :doc:`Symfony Flex </setup/flex>`, run this command to install the workflow feature before using it:

$ composer require symfony/workflow

Creating a Workflow

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 that can have these places: draft, review, rejected, published. You can define the workflow like this:

.. configuration-block::

    .. code-block:: yaml

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

    .. code-block:: 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 http://symfony.com/schema/dic/services/services-1.0.xsd
                http://symfony.com/schema/dic/symfony http://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:place>draft</framework:place>
                    <framework:place>review</framework:place>
                    <framework:place>rejected</framework:place>
                    <framework:place>published</framework:place>

                    <framework:transition name="to_review">
                        <framework:from>draft</framework:from>

                        <framework:to>review</framework:to>
                    </framework:transition>

                    <framework:transition name="publish">
                        <framework:from>review</framework:from>

                        <framework:to>published</framework:to>
                    </framework:transition>

                    <framework:transition name="reject">
                        <framework:from>review</framework:from>

                        <framework:to>rejected</framework:to>
                    </framework:transition>

                </framework:workflow>

            </framework:config>
        </container>

    .. code-block:: php

        // config/packages/workflow.php

        $container->loadFromExtension('framework', array(
            // ...
            'workflows' => array(
                'blog_publishing' => array(
                    'type' => 'workflow', // or 'state_machine'
                    'audit_trail' => array(
                        'enabled' => true
                    ),
                    'marking_store' => array(
                        'type' => 'multiple_state', // or 'single_state'
                        'arguments' => array('currentPlace')
                    ),
                    'supports' => array('App\Entity\BlogPost'),
                    'places' => array(
                        'draft',
                        'review',
                        'rejected',
                        'published',
                    ),
                    'transitions' => array(
                        'to_review' => array(
                            'from' => 'draft',
                            'to' => 'review',
                         ),
                         'publish' => array(
                             'from' => 'review',
                             'to' => 'published',
                         ),
                         'reject' => array(
                             'from' => 'review',
                             'to' => 'rejected',
                         ),
                     ),
                 ),
             ),
         ));

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.

Tip

The type (default value single_state) and arguments (default value marking) attributes of the marking_store option are optional. If omitted, their default values will be used.

Tip

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

Using a Workflow

Once the blog_publishing workflow has been created, you can now use it to decide what actions are allowed on a blog post. For example, inside a controller of an application using the :ref:`default services.yaml configuration <service-container-services-load-example>`, you can get the workflow by injecting the Workflow registry service:

// ...
use Symfony\Component\Workflow\Registry;
use App\Entity\BlogPost;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Workflow\Exception\TransitionException;

class BlogController extends AbstractController
{
    public function edit(Registry $workflows)
    {
        $post = new BlogPost();
        $workflow = $workflows->get($post);

        // if there are multiple workflows for the same class,
        // pass the workflow name as the second argument
        // $workflow = $workflows->get($post, 'blog_publishing');

        // you can also get all workflows associated with an object, which is useful
        // for example to show the status of all those workflows in a backend
        $postWorkflows = $workflows->all($post);

        $workflow->can($post, 'publish'); // False
        $workflow->can($post, 'to_review'); // True

        // Update the currentState on the post
        try {
            $workflow->apply($post, 'to_review');
        } catch (TransitionException $exception) {
            // ... if the transition is not allowed
        }

        // See all the available transitions for the post in the current state
        $transitions = $workflow->getEnabledTransitions($post);
    }
}

.. versionadded:: 4.1
    The :class:`Symfony\\Component\\Workflow\\Exception\\TransitionException`
    class was introduced in Symfony 4.1.

.. versionadded:: 4.1
    The :method:`Symfony\\Component\\Workflow\\Registry::all` method was
    introduced in Symfony 4.1.

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 allowed at all (:ref:`see below <workflow-usage-guard-events>`).