Workflow

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

Installation

In applications using Symfony Flex <symfony-flex>, run this command to install the workflow feature before using it:

$ composer require symfony/workflow

Configuration

To see all configuration options, if you are using the component inside a Symfony 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. Each step or stage in the process is called a place. You also define transitions, which describe the action needed 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 Symfony\\Component\\Workflow\\MarkingStore\\MarkingStoreInterface.)

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

# config/packages/workflow.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:          # defining places manually is optional
                - draft
                - reviewed
                - rejected
                - published
            transitions:
                to_review:
                    from: draft
                    to:   reviewed
                publish:
                    from: reviewed
                    to:   published
                reject:
                    from: reviewed
                    to:   rejected

<!-- 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>
        <!-- or type="state_machine" -->
        <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>

            <!-- defining places manually is optional -->
            <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>

// config/packages/workflow.php
use App\Entity\BlogPost;
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $blogPublishing = $framework->workflows()->workflows('blog_publishing');
    $blogPublishing
        ->type('workflow') // or 'state_machine'
        ->supports([BlogPost::class])
        ->initialMarking(['draft']);

    $blogPublishing->auditTrail()->enabled(true);
    $blogPublishing->markingStore()
        ->type('method')
        ->property('currentPlace');

    // defining places manually is optional
    $blogPublishing->place()->name('draft');
    $blogPublishing->place()->name('reviewed');
    $blogPublishing->place()->name('rejected');
    $blogPublishing->place()->name('published');

    $blogPublishing->transition()
        ->name('to_review')
            ->from(['draft'])
            ->to(['reviewed']);

    $blogPublishing->transition()
        ->name('publish')
            ->from(['reviewed'])
            ->to(['published']);

    $blogPublishing->transition()
        ->name('reject')
            ->from(['reviewed'])
            ->to(['rejected']);
};

Tip

If you are creating your first workflows, consider using the workflow:dump command to debug the workflow contents </workflow/dumping-workflows>.

Tip

You can use PHP constants in YAML files via the !php/const notation. E.g. you can use !php/const App\Entity\BlogPost::STATE_DRAFT instead of 'draft' or !php/const App\Entity\BlogPost::TRANSITION_TO_REVIEW instead of 'to_review'.

Tip

You can omit the places option if your transitions define all the places that are used in the workflow. Symfony will automatically extract the places from the transitions.

7.1

The support for omitting the places option was introduced in Symfony 7.1.

The configured property will be used via its implemented getter/setter methods by the marking store:

// src/Entity/BlogPost.php
namespace App\Entity;

class BlogPost
{
    // the configured marking store property must be declared
    private string $currentPlace;
    private string $title;
    private string $content;

    // getter/setter methods must exist for property access by the marking store
    public function getCurrentPlace(): string
    {
        return $this->currentPlace;
    }

    public function setCurrentPlace(string $currentPlace, array $context = []): void
    {
        $this->currentPlace = $currentPlace;
    }

    // you don't need to set the initial marking in the constructor or any other method;
    // this is configured in the workflow with the 'initial_marking' option
}

It is also possible to use public properties for the marking store. The above class would become the following:

// src/Entity/BlogPost.php
namespace App\Entity;

class BlogPost
{
    // the configured marking store property must be declared
    public string $currentPlace;
    public string $title;
    public string $content;
}

When using public properties, context is not supported. In order to support it, you must declare a setter to write your property:

// src/Entity/BlogPost.php
namespace App\Entity;

class BlogPost
{
    public string $currentPlace;
    // ...

    public function setCurrentPlace(string $currentPlace, array $context = []): void
    {
        // assign the property and do something with the context
    }
}

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. If no state marking store is defined you have to return null in both cases (e.g. the above example should define a return type like App\Entity\BlogPost::getCurrentPlace(): ?array or like App\Entity\BlogPost::getCurrentPlace(): ?string).

Tip

The marking_store.type (the default value depends on the type value) and property (default value ['marking']) attributes of the marking_store option are optional. If omitted, their default values will be used. It's highly recommended 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.

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

use App\Entity\BlogPost;
use Symfony\Component\Workflow\Exception\LogicException;

$post = new BlogPost();
// you don't need to set the initial marking with code; this is configured
// in the workflow with the 'initial_marking' option

$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);
// See a specific available transition for the post in the current state
$transition = $workflow->getEnabledTransition($post, 'publish');

Using a multiple state marking store

If you are creating a workflow </workflow/workflow-and-state-machine>, your marking store may need to contain multiple places at the same time. That's why, if you are using Doctrine, the matching column definition should use the type json:

// src/Entity/BlogPost.php
namespace App\Entity;

use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
class BlogPost
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private int $id;

    #[ORM\Column(type: Types::JSON)]
    private array $currentPlaces;

    // ...
}

Caution

You should not use the type simple_array for your marking store. Inside a multiple state marking store, places are stored as keys with a value of one, such as ['draft' => 1]. If the marking store contains only one place, this Doctrine type will store its value only as a string, resulting in the loss of the object's current place.

Accessing the Workflow in a Class

You can use the workflow inside a class by using service autowiring </service_container/autowiring> and using camelCased workflow name + Workflow as parameter name. If it is a state machine type, use camelCased workflow name + StateMachine:

use App\Entity\BlogPost;
use Symfony\Component\Workflow\WorkflowInterface;

class MyClass
{
    public function __construct(
        // Symfony will inject the 'blog_publishing' workflow configured before
        private WorkflowInterface $blogPublishingWorkflow,
    ) {
    }

    public function toReview(BlogPost $post): void
    {
        // Update the currentState on the post
        try {
            $this->blogPublishingWorkflow->apply($post, 'to_review');
        } catch (LogicException $exception) {
            // ...
        }
        // ...
    }
}

To get the enabled transition of a Workflow, you can use Symfony\\Component\\Workflow\\WorkflowInterface::getEnabledTransition method.

7.1

The Symfony\\Component\\Workflow\\WorkflowInterface::getEnabledTransition method was introduced in Symfony 7.1.

Workflows can also be injected thanks to their name and the Symfony\\Component\\DependencyInjection\\Attribute\\Target attribute:

use App\Entity\BlogPost;
use Symfony\Component\DependencyInjection\Attribute\Target;
use Symfony\Component\Workflow\WorkflowInterface;

class MyClass
{
    public function __construct(
        #[Target('blog_publishing')]
        private WorkflowInterface $workflow
    ) {
    }

    // ...
}

This allows you to decorrelate the argument name of any implementation name.

Tip

If you want to retrieve all workflows, for documentation purposes for example, you can inject all services </service_container/service_subscribers_locators> with the following tag:

workflow: all workflows and all state machine;
workflow.workflow: all workflows;
workflow.state_machine: all state machines.

Note that workflow metadata are attached to tags under the metadata key, giving you more context and information about the workflow at disposal. Learn more about tag attributes <tags_additional-attributes> and storing workflow metadata <workflow_storing-metadata>.

7.1

The attached configuration to the tag was introduced in Symfony 7.1.

Tip

You can find the list of available workflow services with the php bin/console debug:autowiring workflow command.

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 <workflow-usage-guard-events> and blocking transitions <workflow-blocking-transitions>).