Workflow ¶

Installation ¶

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

1

$ composer require symfony/workflow

Configuration ¶

To see all configuration options, if you are using the component inside a Symfony project run this command:

1

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# 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:
                - draft
                - reviewed
                - rejected
                - published
            transitions:
                to_review:
                    from: draft
                    to:   reviewed
                publish:
                    from: reviewed
                    to:   published
                reject:
                    from: reviewed
                    to:   rejected

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

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

return static function (FrameworkConfig $framework) {
    $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');

    $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']);
};

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

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

Accessing the Workflow in a Class ¶

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

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

class MyClass
{
    private $blogPublishingWorkflow;

    // Symfony will inject the 'blog_publishing' workflow configured before
    public function __construct(WorkflowInterface $blogPublishingWorkflow)
    {
        $this->blogPublishingWorkflow = $blogPublishingWorkflow;
    }

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

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 and blocking transitions).

遷移がブロックされているかどうかを検証します (seeguard イベントとブロッキング遷移)。

The three events being dispatched are:

ディスパッチされる 3 つのイベントは次のとおりです。

• workflow.guard
  ワークフロー.ガード
• workflow.[workflow name].guard
  workflow.[ワークフロー名].guard
• workflow.[workflow name].guard.[transition name]
  workflow.[ワークフロー名].guard.[トランジション名]

workflow.leave

The subject is about to leave a place.

対象は場所を離れようとしています。

The three events being dispatched are:

ディスパッチされる 3 つのイベントは次のとおりです。

• workflow.leave
  ワークフロー.残す
• workflow.[workflow name].leave
  workflow.[ワークフロー名].leave
• workflow.[workflow name].leave.[place name]
  workflow.[ワークフロー名].leave.[場所名]

workflow.transition

The subject is going through this transition.

対象はこの移行を通過しています。

The three events being dispatched are:

ディスパッチされる 3 つのイベントは次のとおりです。

• workflow.transition
  ワークフロー.トランジション
• workflow.[workflow name].transition
  workflow.[ワークフロー名].transition
• workflow.[workflow name].transition.[transition name]
  workflow.[ワークフロー名].transition.[トランジション名]

workflow.enter

The subject is about to enter a new place. This event is triggered right before the subject places are updated, which means that the marking of the subject is not yet updated with the new places.

対象は新しい場所に入ろうとしています。このイベントは、サブジェクトの場所が更新される直前にトリガーされます。つまり、サブジェクトのマーキングは新しい場所でまだ更新されていません。

The three events being dispatched are:

ディスパッチされる 3 つのイベントは次のとおりです。

• workflow.enter
  ワークフロー入力
• workflow.[workflow name].enter
  workflow.[ワークフロー名].enter
• workflow.[workflow name].enter.[place name]
  workflow.[ワークフロー名].enter.[場所名]

workflow.entered

The subject has entered in the places and the marking is updated.

箇所に被写体が入り、マーキングが更新されています。

The three events being dispatched are:

ディスパッチされる 3 つのイベントは次のとおりです。

• workflow.entered
  ワークフロー.入力済み
• workflow.[workflow name].entered
  workflow.[ワークフロー名].entered
• workflow.[workflow name].entered.[place name]
  workflow.[ワークフロー名].entered.[場所名]

workflow.completed

The object has completed this transition.

オブジェクトはこの遷移を完了しました。

The three events being dispatched are:

ディスパッチされる 3 つのイベントは次のとおりです。

• workflow.completed
  ワークフロー.完了
• workflow.[workflow name].completed
  ワークフロー.[ワークフロー名].完了
• workflow.[workflow name].completed.[transition name]
  workflow.[ワークフロー名].completed.[トランジション名]

workflow.announce

Triggered for each transition that now is accessible for the subject.

サブジェクトがアクセスできるようになったトランジションごとにトリガーされます。

The three events being dispatched are:

ディスパッチされる 3 つのイベントは次のとおりです。

• workflow.announce
  ワークフロー.アナウンス
• workflow.[workflow name].announce
  workflow.[ワークフロー名].announce
• workflow.[workflow name].announce.[transition name]
  workflow.[ワークフロー名].announce.[トランジション名]

After a transition is applied, the announce event tests for all available transitions. That will trigger all guard events once more, which could impact performance if they include intensive CPU or database workloads.

トランジションが適用された後、アナウンス イベントは使用可能なすべてのトランジションをテストします。これにより、すべてのガード イベントが再度トリガーされ、集中的な CPU またはデータベースのワークロードが含まれる場合、パフォーマンスに影響を与える可能性があります。

If you don't need the announce event, disable it using the context:

アナウンス イベントが必要ない場合は、コンテキストを使用して無効にします。

1	$workflow->apply($subject, $transitionName, [Workflow::DISABLE_ANNOUNCE_EVENT => true]);

The context is accessible in all events except for the workflow.guard events:

1
2
3
4
5
6

// $context must be an array
$context = ['context_key' => 'context_value'];
$workflow->apply($subject, $transitionName, $context);

// in an event listener (workflow.guard events)
$context = $event->getContext(); // returns ['context']

Here is an example of how to enable logging for every time a "blog_publishing" workflow leaves a place:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

// src/App/EventSubscriber/WorkflowLoggerSubscriber.php
namespace App\EventSubscriber;

use Psr\Log\LoggerInterface;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Workflow\Event\Event;

class WorkflowLoggerSubscriber implements EventSubscriberInterface
{
    private $logger;

    public function __construct(LoggerInterface $logger)
    {
        $this->logger = $logger;
    }

    public function onLeave(Event $event)
    {
        $this->logger->alert(sprintf(
            'Blog post (id: "%s") performed transition "%s" from "%s" to "%s"',
            $event->getSubject()->getId(),
            $event->getTransition()->getName(),
            implode(', ', array_keys($event->getMarking()->getPlaces())),
            implode(', ', $event->getTransition()->getTos())
        ));
    }

    public static function getSubscribedEvents()
    {
        return [
            'workflow.blog_publishing.leave' => 'onLeave',
        ];
    }
}

If some listeners update the context during a transition, you can retrieve it via the marking:

1
2
3
4

$marking = $workflow->apply($post, 'to_review');

// contains the new value
$marking->getContext();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

// src/App/EventSubscriber/BlogPostReviewSubscriber.php
namespace App\EventSubscriber;

use App\Entity\BlogPost;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Workflow\Event\GuardEvent;

class BlogPostReviewSubscriber implements EventSubscriberInterface
{
    public function guardReview(GuardEvent $event)
    {
        /** @var BlogPost $post */
        $post = $event->getSubject();
        $title = $post->title;

        if (empty($title)) {
            $event->setBlocked(true, 'This blog post cannot be marked as reviewed because it has no title.');
        }
    }

    public static function getSubscribedEvents()
    {
        return [
            'workflow.blog_publishing.guard.to_review' => ['guardReview'],
        ];
    }
}

1
2
3
4
5
6
7
8
9
10
11

# config/packages/workflow.yaml
framework:
    workflows:
        blog_publishing:
            # you can pass one or more event names
            events_to_dispatch: ['workflow.leave', 'workflow.completed']

            # pass an empty array to not dispatch any event
            events_to_dispatch: []

            # ...

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

<!-- 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>
        <framework:workflow name="blog_publishing">
            <!-- you can pass one or more event names -->
            <framework:event-to-dispatch>workflow.leave</framework:event-to-dispatch>
            <framework:event-to-dispatch>workflow.completed</framework:event-to-dispatch>

            <!-- pass an empty array to not dispatch any event -->
            <framework:event-to-dispatch></framework:event-to-dispatch>

            <!-- ... -->
        </framework:workflow>
    </framework:config>
</container>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

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

return static function (FrameworkConfig $framework) {
    // ...

    $blogPublishing = $framework->workflows()->workflows('blog_publishing');

    // ...
    // you can pass one or more event names
    $blogPublishing->eventsToDispatch([
        'workflow.leave',
        'workflow.completed',
    ]);

    // pass an empty array to not dispatch any event
    $blogPublishing->eventsToDispatch([]);

    // ...
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

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

$post = new BlogPost();

$workflow = $this->container->get('workflow.blog_publishing');

try {
    $workflow->apply($post, 'to_review', [
        Workflow::DISABLE_ANNOUNCE_EVENT => true,
        Workflow::DISABLE_LEAVE_EVENT => true,
    ]);
} catch (LogicException $exception) {
    // ...
}

Blocking Transitions ¶

The execution of the workflow can be controlled by calling custom logic to decide if the current transition is blocked or allowed before applying it. This feature is provided by "guards", which can be used in two ways.

First, you can listen to the guard events. Alternatively, you can define a guard configuration option for the transition. The value of this option is any valid expression created with the ExpressionLanguage component:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# config/packages/workflow.yaml
framework:
    workflows:
        blog_publishing:
            # previous configuration
            transitions:
                to_review:
                    # the transition is allowed only if the current user has the ROLE_REVIEWER role.
                    guard: "is_granted('ROLE_REVIEWER')"
                    from: draft
                    to:   reviewed
                publish:
                    # or "is_anonymous", "is_remember_me", "is_fully_authenticated", "is_granted", "is_valid"
                    guard: "is_authenticated"
                    from: reviewed
                    to:   published
                reject:
                    # or any valid expression language with "subject" referring to the supported object
                    guard: "is_granted('ROLE_ADMIN') and subject.isRejectable()"
                    from: reviewed
                    to:   rejected

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

<!-- 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>
        <framework:workflow name="blog_publishing" type="workflow">

            <!-- ... previous configuration -->

            <framework:transition name="to_review">
                <!-- the transition is allowed only if the current user has the ROLE_REVIEWER role. -->
                <framework:guard>is_granted("ROLE_REVIEWER")</framework:guard>
                <framework:from>draft</framework:from>
                <framework:to>reviewed</framework:to>
            </framework:transition>

            <framework:transition name="publish">
                <!-- or "is_anonymous", "is_remember_me", "is_fully_authenticated", "is_granted" -->
                <framework:guard>is_authenticated</framework:guard>
                <framework:from>reviewed</framework:from>
                <framework:to>published</framework:to>
            </framework:transition>

            <framework:transition name="reject">
                <!-- or any valid expression language with "subject" referring to the post -->
                <framework:guard>is_granted("ROLE_ADMIN") and subject.isStatusReviewed()</framework:guard>
                <framework:from>reviewed</framework:from>
                <framework:to>rejected</framework:to>
            </framework:transition>

        </framework:workflow>

    </framework:config>
</container>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

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

return static function (FrameworkConfig $framework) {
    $blogPublishing = $framework->workflows()->workflows('blog_publishing');
    // ... previous configuration

    $blogPublishing->transition()
        ->name('to_review')
            // the transition is allowed only if the current user has the ROLE_REVIEWER role.
            ->guard('is_granted("ROLE_REVIEWER")')
            ->from(['draft'])
            ->to(['reviewed']);

    $blogPublishing->transition()
        ->name('publish')
            // or "is_anonymous", "is_remember_me", "is_fully_authenticated", "is_granted"
            ->guard('is_authenticated')
            ->from(['reviewed'])
            ->to(['published']);

    $blogPublishing->transition()
        ->name('reject')
            // or any valid expression language with "subject" referring to the post
            ->guard('is_granted("ROLE_ADMIN") and subject.isStatusReviewed()')
            ->from(['reviewed'])
            ->to(['rejected']);
};

You can also use transition blockers to block and return a user-friendly error message when you stop a transition from happening. In the example we get this message from the Event's metadata, giving you a central place to manage the text.

This example has been simplified; in production you may prefer to use the Translation component to manage messages in one place:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

// src/App/EventSubscriber/BlogPostPublishSubscriber.php
namespace App\EventSubscriber;

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Workflow\Event\GuardEvent;
use Symfony\Component\Workflow\TransitionBlocker;

class BlogPostPublishSubscriber implements EventSubscriberInterface
{
    public function guardPublish(GuardEvent $event)
    {
        $eventTransition = $event->getTransition();
        $hourLimit = $event->getMetadata('hour_limit', $eventTransition);

        if (date('H') <= $hourLimit) {
            return;
        }

        // Block the transition "publish" if it is more than 8 PM
        // with the message for end user
        $explanation = $event->getMetadata('explanation', $eventTransition);
        $event->addTransitionBlocker(new TransitionBlocker($explanation , '0'));
    }

    public static function getSubscribedEvents()
    {
        return [
            'workflow.blog_publishing.guard.publish' => ['guardPublish'],
        ];
    }
}

Usage in Twig ¶

Symfony defines several Twig functions to manage workflows and reduce the need of domain logic in your templates:

workflow_can()

Returns true if the given object can make the given transition.

指定されたオブジェクトが指定された遷移を行うことができる場合、true を返します。

workflow_transitions()

Returns an array with all the transitions enabled for the given object.

指定されたオブジェクトで有効になっているすべてのトランジションを含む配列を返します。

workflow_transition()

Returns a specific transition enabled for the given object and transition name.

指定されたオブジェクトとトランジション名に対して有効になっている特定のトランジションを返します。

workflow_marked_places()

Returns an array with the place names of the given marking.

指定されたマーキングの地名の配列を返します。

workflow_has_marked_place()

Returns true if the marking of the given object has the given state.

指定されたオブジェクトのマーキングが指定された状態である場合、true を返します。

workflow_transition_blockers()

Returns TransitionBlockerList for the given transition.

指定されたトランジションの TransitionBlockerList を返します。

The following example shows these functions in action:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

<h3>Actions on Blog Post</h3>
{% if workflow_can(post, 'publish') %}
    <a href="...">Publish</a>
{% endif %}
{% if workflow_can(post, 'to_review') %}
    <a href="...">Submit to review</a>
{% endif %}
{% if workflow_can(post, 'reject') %}
    <a href="...">Reject</a>
{% endif %}

{# Or loop through the enabled transitions #}
{% for transition in workflow_transitions(post) %}
    <a href="...">{{ transition.name }}</a>
{% else %}
    No actions available.
{% endfor %}

{# Check if the object is in some specific place #}
{% if workflow_has_marked_place(post, 'reviewed') %}
    <p>This post is ready for review.</p>
{% endif %}

{# Check if some place has been marked on the object #}
{% if 'reviewed' in workflow_marked_places(post) %}
    <span class="label">Reviewed</span>
{% endif %}

{# Loop through the transition blockers #}
{% for blocker in workflow_transition_blockers(post, 'publish') %}
    <span class="error">{{ blocker.message }}</span>
{% endfor %}

Storing Metadata ¶

In case you need it, you can store arbitrary metadata in workflows, their places, and their transitions using the metadata option. This metadata can be only the title of the workflow or very complex objects:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# config/packages/workflow.yaml
framework:
    workflows:
        blog_publishing:
            metadata:
                title: 'Blog Publishing Workflow'
            # ...
            places:
                draft:
                    metadata:
                        max_num_of_words: 500
                # ...
            transitions:
                to_review:
                    from: draft
                    to:   review
                    metadata:
                        priority: 0.5
                publish:
                    from: reviewed
                    to:   published
                    metadata:
                        hour_limit: 20
                        explanation: 'You can not publish after 8 PM.'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

<!-- 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>
        <framework:workflow name="blog_publishing">
            <framework:metadata>
                <framework:title>Blog Publishing Workflow</framework:title>
            </framework:metadata>
            <!-- ... -->
            <framework:place name="draft">
                <framework:metadata>
                    <framework:max-num-of-words>500</framework:max-num-of-words>
                </framework:metadata>
            </framework:place>
            <!-- ... -->
            <framework:transition name="to_review">
                <framework:from>draft</framework:from>
                <framework:to>review</framework:to>
                <framework:metadata>
                    <framework:priority>0.5</framework:priority>
                </framework:metadata>
            </framework:transition>
            <framework:transition name="publish">
                <framework:from>reviewed</framework:from>
                <framework:to>published</framework:to>
                <framework:metadata>
                    <framework:hour_limit>20</framework:hour_limit>
                    <framework:explanation>You can not publish after 8 PM.</framework:explanation>
                </framework:metadata>
            </framework:transition>
        </framework:workflow>
    </framework:config>
</container>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

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

return static function (FrameworkConfig $framework) {
    $blogPublishing = $framework->workflows()->workflows('blog_publishing');
    // ... previous configuration

    $blogPublishing->metadata([
        'title' => 'Blog Publishing Workflow'
    ]);

    // ...

    $blogPublishing->place()
        ->name('draft')
        ->metadata([
            'max_num_of_words' => 500,
        ]);

    // ...

    $blogPublishing->transition()
        ->name('to_review')
            ->from(['draft'])
            ->to(['reviewed'])
            ->metadata([
                'priority' => 0.5,
            ]);

    $blogPublishing->transition()
        ->name('publish')
            ->from(['reviewed'])
            ->to(['published'])
            ->metadata([
                'hour_limit' => 20,
                'explanation' => 'You can not publish after 8 PM.',
            ]);
};

Then you can access this metadata in your controller as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

// src/App/Controller/BlogPostController.php
use App\Entity\BlogPost;
use Symfony\Component\Workflow\WorkflowInterface;
// ...

public function myAction(WorkflowInterface $blogPublishingWorkflow, BlogPost $post)
{
    $title = $blogPublishingWorkflow
        ->getMetadataStore()
        ->getWorkflowMetadata()['title'] ?? 'Default title'
    ;

    $maxNumOfWords = $blogPublishingWorkflow
        ->getMetadataStore()
        ->getPlaceMetadata('draft')['max_num_of_words'] ?? 500
    ;

    $aTransition = $blogPublishingWorkflow->getDefinition()->getTransitions()[0];
    $priority = $blogPublishingWorkflow
        ->getMetadataStore()
        ->getTransitionMetadata($aTransition)['priority'] ?? 0
    ;

    // ...
}

There is a getMetadata() method that works with all kinds of metadata:

1
2
3
4
5
6
7
8

// get "workflow metadata" passing the metadata key as argument
$title = $workflow->getMetadataStore()->getMetadata('title');

// get "place metadata" passing the metadata key as the first argument and the place name as the second argument
$maxNumOfWords = $workflow->getMetadataStore()->getMetadata('max_num_of_words', 'draft');

// get "transition metadata" passing the metadata key as the first argument and a Transition object as the second argument
$priority = $workflow->getMetadataStore()->getMetadata('priority', $aTransition);

In a flash message in your controller:

1
2
3
4
5

// $transition = ...; (an instance of Transition)

// $workflow is a Workflow instance retrieved from the Registry or injected directly (see above)
$title = $workflow->getMetadataStore()->getMetadata('title', $transition);
$this->addFlash('info', "You have successfully applied the transition with title: '$title'");

Metadata can also be accessed in a Listener, from the Event object.

In Twig templates, metadata is available via the workflow_metadata() function:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

<h2>Metadata of Blog Post</h2>
<p>
    <strong>Workflow</strong>:<br>
    <code>{{ workflow_metadata(blog_post, 'title') }}</code>
</p>
<p>
    <strong>Current place(s)</strong>
    <ul>
        {% for place in workflow_marked_places(blog_post) %}
            <li>
                {{ place }}:
                <code>{{ workflow_metadata(blog_post, 'max_num_of_words', place) ?: 'Unlimited'}}</code>
            </li>
        {% endfor %}
    </ul>
</p>
<p>
    <strong>Enabled transition(s)</strong>
    <ul>
        {% for transition in workflow_transitions(blog_post) %}
            <li>
                {{ transition.name }}:
                <code>{{ workflow_metadata(blog_post, 'priority', transition) ?: 0 }}</code>
            </li>
        {% endfor %}
    </ul>
</p>
<p>
    <strong>to_review Priority</strong>
    <ul>
        <li>
            to_review:
            <code>{{ workflow_metadata(blog_post, 'priority', workflow_transition(blog_post, 'to_review')) }}</code>
        </li>
    </ul>
</p>

Learn more ¶