Table of Contents

Workflow

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

Installation

In applications usingSymfony 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

A workflow is a process or a lifecycle that your objects go through. Eachstep or stage in the process is called aplace. You also definetransitions,which describe the action needed to get from one place to another.

An example state diagram for a workflow, showing transitions and places.

A set of places and transitions creates adefinition. A workflow needsaDefinition and a way to write the states to the objects (i.e. aninstance of aMarkingStoreInterface.)

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

12345678910111213141516171819202122232425262728

# config/packages/workflow.yamlframework:workflows:blog_publishing:type:'workflow'# or 'state_machine'audit_trail:enabled:truemarking_store:type:'method'property:'currentPlace'supports:-App\Entity\BlogPostinitial_marking:draftplaces:# defining places manually is optional-draft-reviewed-rejected-publishedtransitions:to_review:from:draftto:reviewedpublish:from:reviewedto:publishedreject:from:reviewedto:rejected

1234567891011121314151617181920212223242526272829303132333435363738394041

<!-- config/packages/workflow.xml --><?xml version="1.0" encoding="UTF-8" ?><containerxmlns="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:workflowname="blog_publishing"type="workflow"><framework:audit-trailenabled="true"/><framework:marking-storetype="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:transitionname="to_review"><framework:from>draft</framework:from><framework:to>reviewed</framework:to></framework:transition><framework:transitionname="publish"><framework:from>reviewed</framework:from><framework:to>published</framework:to></framework:transition><framework:transitionname="reject"><framework:from>reviewed</framework:from><framework:to>rejected</framework:to></framework:transition></framework:workflow></framework:config></container>

12345678910111213141516171819202122232425262728293031323334353637

// config/packages/workflow.phpuseApp\Entity\BlogPost;useSymfony\Config\FrameworkConfig;returnstaticfunction(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 theworkflow:dumpcommand todebug the workflow contents.

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_REVIEWinstead of'to_review'.

Tip

You can omit theplaces option if your transitions define all the placesthat are used in the workflow. Symfony will automatically extract the placesfrom the transitions.

7.1

The support for omitting theplaces option was introduced inSymfony 7.1.

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

123456789101112131415161718192021222324

// src/Entity/BlogPost.phpnamespaceApp\Entity;classBlogPost{// the configured marking store property must be declaredprivatestring$currentPlace;privatestring$title;privatestring$content;// getter/setter methods must exist for property access by the marking storepublicfunctiongetCurrentPlace():string{return$this->currentPlace;    }publicfunctionsetCurrentPlace(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 aboveclass would become the following:

12345678910

// src/Entity/BlogPost.phpnamespaceApp\Entity;classBlogPost{// the configured marking store property must be declaredpublicstring$currentPlace;publicstring$title;publicstring$content;}

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

12345678910111213

// src/Entity/BlogPost.phpnamespaceApp\Entity;classBlogPost{publicstring$currentPlace;// ...publicfunctionsetCurrentPlace(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 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 astring to store the data. A multiplestate marking store uses anarray to store the data. If no state markingstore is defined you have to returnnull in both cases (e.g. the aboveexample should define a return type likeApp\Entity\BlogPost::getCurrentPlace(): ?arrayor likeApp\Entity\BlogPost::getCurrentPlace(): ?string).

Tip

Themarking_store.type (the default value depends on thetype value)andproperty (default value['marking']) attributes of themarking_store option are optional. If omitted, their default values willbe used. It's highly recommended to use the default value.

Tip

Setting theaudit_trail.enabled option totrue makes the applicationgenerate detailed log messages for the workflow activity.

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

12345678910111213141516171819202122

useApp\Entity\BlogPost;useSymfony\Component\Workflow\Exception\LogicException;$post =newBlogPost();// 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 posttry {$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 aworkflow,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 typejson:

12345678910111213141516171819

// src/Entity/BlogPost.phpnamespaceApp\Entity;useDoctrine\DBAL\Types\Types;useDoctrine\ORM\MappingasORM;#[ORM\Entity]classBlogPost{#[ORM\Id]#[ORM\GeneratedValue]#[ORM\Column]privateint$id;#[ORM\Column(type: Types::JSON)]privatearray$currentPlaces;// ...}

Warning

You should not use the typesimple_array for your marking store. Insidea 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 theloss of the object's current place.

Accessing the Workflow in a Class

Symfony creates a service for each workflow you define. You have two ways ofinjecting each workflow in any service or controller:

(1) Use a specific argument name

Type-hint your constructor/method argument withWorkflowInterface and name theargument using this pattern: "workflow name in camelCase" +Workflow suffix.If it is a state machine type, use theStateMachine suffix.

For example, to inject theblog_publishing workflow defined earlier:

123456789101112131415161718192021

useApp\Entity\BlogPost;useSymfony\Component\Workflow\WorkflowInterface;classMyClass{publicfunction__construct(private WorkflowInterface$blogPublishingWorkflow,    ){    }publicfunctiontoReview(BlogPost$post):void{try {// update the currentState on the post$this->blogPublishingWorkflow->apply($post,'to_review');        }catch (LogicException$exception) {// ...        }// ...    }}

(2) Use the#[Target] attribute

Whendealing with multiple implementations of the same typethe#[Target] attribute helps you select which one to inject. Symfony createsa target with the same name as each workflow.

For example, to select theblog_publishing workflow defined earlier:

123456789101112

useSymfony\Component\DependencyInjection\Attribute\Target;useSymfony\Component\Workflow\WorkflowInterface;classMyClass{publicfunction__construct(#[Target('blog_publishing')]private WorkflowInterface$workflow,    ){    }// ...}

To get the enabled transition of a Workflow, you can usegetEnabledTransition()method.

7.1

ThegetEnabledTransition()method was introduced in Symfony 7.1.

Tip

If you want to retrieve all workflows, for documentation purposes for example,you caninject all serviceswith 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 themetadata key,giving you more context and information about the workflow at disposal.Learn more abouttag attributes andstoring workflow 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 thephp bin/console debug:autowiring workflow command.

Injecting Multiple Workflows

Use theAutowireLocator attribute tolazy-load all workflows and get the one you need:

1234567891011121314151617181920212223

useSymfony\Component\DependencyInjection\Attribute\AutowireLocator;useSymfony\Component\DependencyInjection\ServiceLocator;classMyClass{publicfunction__construct(        //'workflow' is the service tag name and injects both workflows and state machines;        //'name' tells Symfony to index services using that tag property#[AutowireLocator('workflow','name')]private ServiceLocator$workflows,    ){    }publicfunctionsomeMethod():void{// if you use the 'name' tag property to index services (see constructor above),// you can get workflows by their name; otherwise, you must use the full// service name with the 'workflow.' prefix (e.g. 'workflow.user_registration')$workflow =$this->workflows->get('user_registration');// ...    }}

Tip

You can also inject only workflows or only state machines:

publicfunction__construct(#[AutowireLocator('workflow.workflow','name')]private ServiceLocator$workflows,#[AutowireLocator('workflow.state_machine','name')]private ServiceLocator$stateMachines,){}

Using Events

To make your workflows more flexible, you can construct theWorkflowobject with anEventDispatcher. 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).