Skip to content

Commit f9c506a

Browse files
noniagriconomienoniagriconomie
committed
Merge branch 'feature-workflow-config' of https://github.com/noniagriconomie/symfony-docs into feature-workflow-config
2 parents 83685b6 + c029eae commit f9c506a

File tree

2 files changed

+46
-280
lines changed

2 files changed

+46
-280
lines changed

‎workflow.rst

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -182,21 +182,21 @@ what actions are allowed on a blog post::
182182
use App\Entity\BlogPost;
183183
use Symfony\Component\Workflow\Exception\LogicException;
184184

185-
$post = BlogPost();
185+
$blogPost = BlogPost();
186186

187187
$workflow = $this->container->get('workflow.blog_publishing');
188-
$workflow->can($post, 'publish'); // False
189-
$workflow->can($post, 'to_review'); // True
188+
$workflow->can($blogPost, 'publish'); // False
189+
$workflow->can($blogPost, 'to_review'); // True
190190

191191
// Update the currentState on the post
192192
try {
193-
$workflow->apply($post, 'to_review');
193+
$workflow->apply($blogPost, 'to_review');
194194
} catch (LogicException $exception) {
195195
// ...
196196
}
197197

198198
// See all the available transitions for the post in the current state
199-
$transitions = $workflow->getEnabledTransitions($post);
199+
$transitions = $workflow->getEnabledTransitions($blogPost);
200200

201201
Using Events
202202
------------
@@ -350,9 +350,9 @@ missing a title::
350350
{
351351
public function guardReview(GuardEvent $event)
352352
{
353-
/** @var App\Entity\BlogPost $post */
354-
$post = $event->getSubject();
355-
$title = $post->title;
353+
/** @var App\Entity\BlogPost $blogPost */
354+
$blogPost = $event->getSubject();
355+
$title = $blogPost->title;
356356

357357
if (empty($title)) {
358358
// Block the transition "to_review" if the post has no title
@@ -466,7 +466,7 @@ place::
466466
$eventTransition = $event->getTransition();
467467
$hourLimit = $event->getMetadata('hour_limit', $eventTransition);
468468

469-
if (date('H') <= $hourLimit) {
469+
if ((int) date('H') <= (int) $hourLimit) {
470470
return;
471471
}
472472

@@ -664,10 +664,11 @@ Then you can access this metadata in your controller as follows::
664664

665665
use App\Entity\BlogPost;
666666
use Symfony\Component\Workflow\Registry;
667+
use App\Entity\BlogPost;
667668

668-
public function myController(Registry $registry, BlogPost $post)
669+
public function myController(Registry $registry, BlogPost $blogPost)
669670
{
670-
$workflow = $registry->get($post);
671+
$workflow = $registry->get($blogPost);
671672

672673
$title = $workflow
673674
->getMetadataStore()

‎workflow/dumping-workflows.rst

Lines changed: 34 additions & 269 deletions
Original file line numberDiff line numberDiff line change
@@ -4,295 +4,60 @@
44
How to Dump Workflows
55
=====================
66

7-
To help you debug your workflows, you can generate a visual representation of
8-
them as SVG or PNG images. First, install any of these free and open source
9-
applications needed to generate the images:
7+
To help you debug your workflows, you can dump a representation of your workflow
8+
or state machine with the use of a ``DumperInterface``. Symfony provides two
9+
different dumpers, both based on Dot (see below).
1010

11-
* `Graphviz`_, provides the ``dot`` command;
12-
* `PlantUML`_, provides the ``plantuml.jar`` file (which requires Java).
11+
Use the ``GraphvizDumper`` or ``StateMachineGraphvizDumper`` to create DOT
12+
files, or use ``PlantUmlDumper`` for PlantUML files. Both types can be converted
13+
to PNG or SVG images.
1314

14-
If you are defining the workflow inside a Symfony application, run this command
15-
to dump it as an image:
15+
Images of the workflow defined above::
1616

17-
.. code-block:: terminal
18-
19-
# using Graphviz's 'dot' and SVG images
20-
$ php bin/console workflow:dump workflow-name | dot -Tsvg -o graph.svg
21-
22-
# using Graphviz's 'dot' and PNG images
23-
$ php bin/console workflow:dump workflow-name | dot -Tpng -o graph.png
24-
25-
# using PlantUML's 'plantuml.jar'
26-
$ php bin/console workflow:dump workflow_name --dump-format=puml | java -jar plantuml.jar -p > graph.png
27-
28-
# highlight 'place1' and 'place2' in the dumped workflow
29-
$ php bin/console workflow:dump workflow-name place1 place2 | dot -Tsvg -o graph.svg
30-
31-
The DOT image will look like this:
32-
33-
.. image:: /_images/components/workflow/blogpost.png
34-
35-
The PlantUML image will look like this:
36-
37-
.. image:: /_images/components/workflow/blogpost_puml.png
38-
39-
If you are creating workflows outside of a Symfony application, use the
40-
``GraphvizDumper`` or ``StateMachineGraphvizDumper`` class to create the DOT
41-
files and ``PlantUmlDumper`` to create the PlantUML files::
42-
43-
// Add this code to a PHP script; for example: dump-graph.php
17+
// dump-graph-dot.php
4418
$dumper = new GraphvizDumper();
4519
echo $dumper->dump($definition);
4620

47-
# if you prefer PlantUML, use this code:
48-
# $dumper = new PlantUmlDumper();
49-
# echo $dumper->dump($definition);
21+
// dump-graph-puml.php
22+
$dumper = new PlantUmlDumper();
23+
echo $dumper->dump($definition);
5024

5125
.. code-block:: terminal
5226
53-
# replace 'dump-graph.php' by the name of your PHP script
54-
$ php dump-graph.php | dot -Tsvg -o graph.svg
55-
$ php dump-graph.php | java -jar plantuml.jar -p > graph.png
56-
57-
Styling
58-
-------
59-
60-
You can use ``metadata`` with the following keys to style the workflow:
61-
62-
* for places:
63-
* ``bg_color``: a color;
64-
* ``description``: a string that describes the state.
65-
* for transitions:
66-
* ``label``: a string that replaces the name of the transition;
67-
* ``color``: a color;
68-
* ``arrow_color``: a color.
69-
70-
Strings can include ``\n`` characters to display the contents in multiple lines.
71-
Colors can be defined as:
72-
73-
* a color name from `PlantUML's color list`_;
74-
* an hexadecimal color (both ``#AABBCC`` and ``#ABC`` formats are supported).
75-
76-
Below is the configuration for the pull request state machine with styling added.
77-
78-
.. configuration-block::
27+
# dump DOT file in PNG image:
28+
$ php dump-graph-dot.php | dot -Tpng -o dot_graph.png
7929
80-
.. code-block:: yaml
30+
# dump DOT file in SVG image:
31+
# $ php dump-graph-dot.php | dot -Tsvg -o dot_graph.svg
8132
82-
# config/packages/workflow.yaml
83-
framework:
84-
workflows:
85-
pull_request:
86-
type: 'state_machine'
87-
supports:
88-
- App\Entity\PullRequest
89-
initial_place: start
90-
places:
91-
start: ~
92-
coding: ~
93-
test: ~
94-
review:
95-
metadata:
96-
description: Human review
97-
merged: ~
98-
closed:
99-
metadata:
100-
bg_color: DeepSkyBlue
101-
transitions:
102-
submit:
103-
from: start
104-
to: test
105-
update:
106-
from: [coding, test, review]
107-
to: test
108-
metadata:
109-
arrow_color: Turquoise
110-
wait_for_review:
111-
from: test
112-
to: review
113-
metadata:
114-
color: Orange
115-
request_change:
116-
from: review
117-
to: coding
118-
accept:
119-
from: review
120-
to: merged
121-
metadata:
122-
label: Accept PR
123-
reject:
124-
from: review
125-
to: closed
126-
reopen:
127-
from: closed
128-
to: review
33+
# dump PlantUML in PNG image:
34+
$ php dump-graph-puml.php | java -jar plantuml.jar -p > puml_graph.png
12935
130-
.. code-block:: xml
36+
The DOT result will look like this:
13137

132-
<!-- config/packages/workflow.xml -->
133-
<?xml version="1.0" encoding="UTF-8" ?>
134-
<container xmlns="http://symfony.com/schema/dic/services"
135-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
136-
xmlns:framework="http://symfony.com/schema/dic/symfony"
137-
xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd
138-
http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
139-
>
140-
141-
<framework:config>
142-
<framework:workflow name="pull_request" type="state_machine">
143-
<framework:marking-store type="single_state"/>
144-
145-
<framework:support>App\Entity\PullRequest</framework:support>
146-
147-
<framework:place>start</framework:place>
148-
<framework:place>coding</framework:place>
149-
<framework:place>test</framework:place>
150-
<framework:place name="review">
151-
<framework:metadata>
152-
<framework:description>Human review</framework:description>
153-
</framework:metadata>
154-
</framework:place>
155-
<framework:place>merged</framework:place>
156-
<framework:place name="closed">
157-
<framework:metadata>
158-
<framework:bg_color>DeepSkyBlue</framework:bg_color>
159-
</framework:metadata>
160-
</framework:place>
161-
</framework:place>
162-
163-
<framework:transition name="submit">
164-
<framework:from>start</framework:from>
165-
166-
<framework:to>test</framework:to>
167-
</framework:transition>
168-
169-
<framework:transition name="update">
170-
<framework:from>coding</framework:from>
171-
<framework:from>test</framework:from>
172-
<framework:from>review</framework:from>
173-
174-
<framework:to>test</framework:to>
175-
176-
<framework:metadata>
177-
<framework:arrow_color>Turquoise</framework:arrow_color>
178-
</framework:metadata>
179-
</framework:transition>
180-
181-
<framework:transition name="wait_for_review">
182-
<framework:from>test</framework:from>
183-
184-
<framework:to>review</framework:to>
185-
186-
<framework:metadata>
187-
<framework:color>Orange</framework:color>
188-
</framework:metadata>
189-
</framework:transition>
190-
191-
<framework:transition name="request_change">
192-
<framework:from>review</framework:from>
193-
194-
<framework:to>coding</framework:to>
195-
</framework:transition>
196-
197-
<framework:transition name="accept">
198-
<framework:from>review</framework:from>
199-
200-
<framework:to>merged</framework:to>
201-
202-
<framework:metadata>
203-
<framework:label>Accept PR</framework:label>
204-
</framework:metadata>
205-
</framework:transition>
206-
207-
<framework:transition name="reject">
208-
<framework:from>review</framework:from>
38+
.. image:: /_images/components/workflow/blogpost.png
20939

210-
<framework:to>closed</framework:to>
211-
</framework:transition>
40+
The PlantUML result:
21241

213-
<framework:transition name="reopen">
214-
<framework:from>closed</framework:from>
42+
.. image:: /_images/components/workflow/blogpost_puml.png
21543

216-
<framework:to>review</framework:to>
217-
</framework:transition>
44+
Inside a Symfony application, you can dump the files with those commands using
45+
``workflow:dump`` command:
21846

219-
</framework:workflow>
47+
.. code-block:: terminal
22048
221-
</framework:config>
222-
</container>
49+
$ php bin/console workflow:dump workflow_name | dot -Tpng -o workflow_name.png
50+
$ php bin/console workflow:dump workflow_name | dot -Tsvg -o workflow_name.svg
51+
$ php bin/console workflow:dump workflow_name --dump-format=puml | java -jar plantuml.jar -p > workflow_name.png
22352
224-
.. code-block:: php
53+
.. note::
22554

226-
// config/packages/workflow.php
227-
$container->loadFromExtension('framework', [
228-
// ...
229-
'workflows' => [
230-
'pull_request' => [
231-
'type' => 'state_machine',
232-
'supports' => ['App\Entity\PullRequest'],
233-
'places' => [
234-
'start',
235-
'coding',
236-
'test',
237-
'review' => [
238-
'metadata' => [
239-
'description' => 'Human review',
240-
],
241-
],
242-
'merged',
243-
'closed' => [
244-
'metadata' => [
245-
'bg_color' => 'DeepSkyBlue',
246-
],
247-
],
248-
],
249-
'transitions' => [
250-
'submit'=> [
251-
'from' => 'start',
252-
'to' => 'test',
253-
],
254-
'update'=> [
255-
'from' => ['coding', 'test', 'review'],
256-
'to' => 'test',
257-
'metadata' => [
258-
'arrow_color' => 'Turquoise',
259-
],
260-
],
261-
'wait_for_review'=> [
262-
'from' => 'test',
263-
'to' => 'review',
264-
'metadata' => [
265-
'color' => 'Orange',
266-
],
267-
],
268-
'request_change'=> [
269-
'from' => 'review',
270-
'to' => 'coding',
271-
],
272-
'accept'=> [
273-
'from' => 'review',
274-
'to' => 'merged',
275-
'metadata' => [
276-
'label' => 'Accept PR',
277-
],
278-
],
279-
'reject'=> [
280-
'from' => 'review',
281-
'to' => 'closed',
282-
],
283-
'reopen'=> [
284-
'from' => 'start',
285-
'to' => 'review',
286-
],
287-
],
288-
],
289-
],
290-
]);
55+
The ``dot`` command is part of Graphviz. You can download it and read
56+
more about it on `Graphviz.org`_.
29157

292-
The PlantUML image will look like this:
58+
The ``plantuml.jar`` command is part of PlantUML. You can download it and
59+
read more about it on `PlantUML.com`_.
29360

294-
.. image:: /_images/components/workflow/pull_request_puml_styled.png
29561

296-
.. _`Graphviz`: http://www.graphviz.org
297-
.. _`PlantUML`: http://plantuml.com/
298-
.. _`PlantUML's color list`: http://plantuml.com/en/color
62+
.. _Graphviz.org: http://www.graphviz.org
63+
.. _PlantUML.com: http://plantuml.com/

0 commit comments

Comments
 (0)