New in Symfony 4.1: Workflow improvements

New PlantUML dumper

Contributed by Sébastien Morel in #24705

Workflows can already be exported to the well-known DOT format and then transformed into image files. In Symfony 4.1 we added support for other popular format called PlantUML. So now you can choose the format that best suits you:

1
2
3
4
5

# traditional DOT-based dumping
$ bin/console workflow:dump my_workflow | dot -Tpng > my_workflow.png

# new PlantUML-based dumping
$ bin/console workflow:dump my_workflow --dump-format=puml | java -jar plantuml.jar -p > my_workflow.png

Removed constraints on transition/place names

Contributed by Grégoire Pineau in #26079

Previously the names of the workflow transitions and places could only contain the characters that matched this regular expression: [\w_-]. Now you can use any character in those names.

New WorkflowInterface and WorkflowSupportStrategyInterface interfaces

Contributed by Hamza Amrouche in #24751

The Workflow class now implements the new WorkflowInterface. This interface contains the same methods of the existing class (getMarking(), can(), apply(), getEnabledTransitions(), getName(), getDefinition() and getMarkingStore()) so you don't have to make any change in your code.

In addition, a new WorkflowSupportStrategyInterface has been created to replace the now deprecated SupportStrategyInterface. The new interface only contains the supports() method, so again you don't need to change anything in your code except the interface class.

Added transition blockers

Contributed by Grégoire Pineau in #26076

The new transition blockers defined via the TransitionBlocker class allow you to give more information about why a transition couldn't happen in the workflow:

1
2
3

$event->addTransitionBlocker(
    new TransitionBlocker('You can not publish this article because it\'s too late. Try again tomorrow morning.')
);

And then you can access to this information in PHP code and Twig templates too:

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

<h2>Why you can't transition?</h2>
<ul>
    {% for transition in workflow_all_transitions(article) %}
        {% if not workflow_can(article, transition.name) %}
            <li>
                <strong>{{ transition.name }}</strong>:
                <ul>
                {% for blocker in workflow_build_transition_blocker_list(article, transition.name) %}
                    <li>
                        {{ blocker.message }}
                        {% if blocker.parameters.expression is defined %}
                            <code>{{ blocker.parameters.expression }}</code>
                        {% endif %}
                    </li>
                {% endfor %}
                </ul>
            </li>
        {% endif %}
    {% endfor %}
</ul>

Allow to store metadata

Contributed by Grégoire Pineau in #26092

You can now store arbitrary metadata in places, transitions and workflows using the metadata option:

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

# config/packages/workflow.yaml
framework:
    workflows:
        my_workflow:
            supports:
                - App\Entity\BlogPost
            metadata:
                some_key: 'some_value'
                other_key: 'other_value'
            # ...
            places:
                some_place:
                    metadata:
                        some_key: 'some_value'
            # ...
            transitions:
                some_transition:
                    metadata:
                        some_key: 'some_value'

Metadata is stored using objects that implement MetadataStoreInterface and it can be obtained with the getMetadata() method:

1
2
3
4
5
6

public function onReview(Event $event) {
    $metadataStore = $event->getWorkflow()->getMetadataStore();
    foreach ($event->getTransition()->getTos() as $place) {
        $this->flashbag->add('info', $metadataStore->getPlaceMetadata($place)->get('some_key'));
    }
}

In Twig templates you can use the new workflow_metadata() function:

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

<strong>Current place(s)</strong>
<ul>
{% for place in workflow_marked_places(article) %}
    <li>
        {{ place }}:
        <code>{{ workflow_metadata(article, 'title', place) ?: 'n-a'}}</code>
    </li>
{% endfor %}
</ul>

<strong>Enabled transition(s)</strong>
<ul>
{% for transition in workflow_transitions(article) %}
    <li>
        {{ transition.name }}:
        <code>{{ workflow_metadata(article, 'title', transition) ?: 'n-a'}}</code>
    </li>
{% endfor %}
</ul>

Added a new TransitionException class

Contributed by Andrew Tchircoff in #26587

When a transition cannot be applied for the workflow, a new Symfony\Component\Workflow\Exception\TransitionException is thrown instead of the previous generic LogicException.