8000 Documentation workflow context apply · symfony/symfony-docs@85220e1 · GitHub
[go: up one dir, main page]
Skip to content

Commit 85220e1

Browse files
noniagriconomiexabbuh
noniagriconomie
authored and
xabbuh
committed
Documentation workflow context apply
1 parent 9b550c6 commit 85220e1

File tree

4 files changed

+114
-5
lines changed

4 files changed

+114
-5
lines changed

‎contributing/documentation/overview.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -284,6 +284,10 @@ If you don't use Docker, follow these steps to build the docs locally:
284284
285285
The generated documentation is available in the ``_build/html`` directory.
286286

287+
.. tip::
288+
289+
You can also use `Docker`_ that wraps all this for you!
< 8000 /td>290+
287291
Frequently Asked Questions
288292
--------------------------
289293

@@ -346,3 +350,4 @@ definitely don't want you to waste your time!
346350
.. _`pip installation`: https://pip.pypa.io/en/stable/installing/
347351
.. _`Sphinx`: http://sphinx-doc.org/
348352
.. _`Sphinx Extensions for PHP and Symfony`: https://github.com/fabpot/sphinx-php
353+
.. _`Docker`: https://github.com/symfony/symfony-docs#docker

‎workflow.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,9 @@ best kept away from your models and should be defined in configuration.
88

99
A **definition** of a workflow consist of places and actions to get from one
1010
place to another. The actions are called **transitions**. A workflow does also
11-
need to know each object's position in the workflow. That **marking store** writes
12-
to a property of the object to remember the current place.
11+
need to know each position an object can be in the workflow. This is the goal of the
12+
**marking store** that reads from and writes to a property of the object, or somewhere else, the current **place(s)**
13+
to remember.
1314

1415
.. note::
1516

‎workflow/state-machines.rst

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -209,6 +209,33 @@ you can get this state machine by injecting the Workflow registry service::
209209
public function someMethod($subject)
210210
{
211211
$stateMachine = $this->workflows->get($subject, 'pull_request');
212+
$stateMachine->apply($subject, 'wait_for_review');
213+
// ...
214+
}
215+
216+
// ...
217+
}
218+
219+
Symfony also creates automatically for you a service for each workflow (:class:`Symfony\\Component\\Workflow\\Workflow`) or state machine (:class:`Symfony\\Component\\Workflow\\StateMachine`) you have defined in your configuration.
220+
This means that you can use respectively ``workflow.pull_request`` or ``state_machine.pull_request`` in your service definition to have directly the proper service::
221+
222+
// ...
223+
use Symfony\Component\Workflow\StateMachine;
224+
225+
class SomeService
226+
{
227+
private $stateMachine;
228+
229+
public function __construct(StateMachine $stateMachine)
230+
{
231+
$this->stateMachine = $stateMachine;
232+
}
233+
234+
public function someMethod($subject)
235+
{
236+
$this->stateMachine->apply($subject, 'wait_for_review', [
237+
'log_comment' => 'My logging comment for the wait for review transition.',
238+
]);
212239
// ...
213240
}
214241

‎workflow/usage.rst

Lines changed: 79 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ like this:
4343
audit_trail:
4444
enabled: true
4545
marking_store:
46-
type: 'multiple_state' # or 'single_state'
46+
type: 'multiple_state' # or 'single_state', 'method' ('method' was added in 4.3)
4747
arguments:
4848
- 'currentPlace'
4949
supports:
@@ -126,7 +126,7 @@ like this:
126126
'enabled' => true
127127
],
128128
'marking_store' => [
129-
'type' => 'multiple_state', // or 'single_state'
129+
'type' => 'multiple_state', // or 'single_state', 'method' ('method' was added in 4.3)
130130
'arguments' => ['currentPlace'],
131131
],
132132
'supports' => ['App\Entity\BlogPost'],
@@ -166,7 +166,7 @@ As configured, the following property is used by the marking store::
166166

167167 A3E2
.. note::
168168

169-
The marking store type could be "multiple_state" or "single_state".
169+
The marking store type could be "multiple_state", "single_state" or "method".
170170
A single state marking store does not support a model being on multiple places
171171
at the same time.
172172

@@ -220,11 +220,87 @@ you can get the workflow by injecting the Workflow registry service::
220220
// ... if the transition is not allowed
221221
}
222222

223+
// Update the currentState on the post passing some contextual data
224+
// to the whole workflow process
225+
try {
226+
$workflow->apply($post, 'publish', [
227+
'log_comment' => 'My logging comment for the publish transition.',
228+
]);
229+
} catch (TransitionException $exception) {
230+
// ... if the transition is not allowed
231+
}
232+
223233
// See all the available transitions for the post in the current state
224234
$transitions = $workflow->getEnabledTransitions($post);
225235
}
226236
}
227237

238+
.. versionadded:: 4.1
239+
240+
The :class:`Symfony\\Component\\Workflow\\Exception\\TransitionException`
241+
class was introduced in Symfony 4.1.
242+
243+
.. versionadded:: 4.1
244+
245+
The :method:`Symfony\\Component\\Workflow\\Registry::all` method was
246+
introduced in Symfony 4.1.
247+
248+
.. versionadded:: 4.3
249+
250+
The :method:`Symfony\\Component\\Workflow\\Workflow::apply` has now a new parameter ``$context``
251+
that is passed to the :class:`Symfony\\Component\\Workflow\\MarkingStore\\MarkingStoreInterface`
252+
:method:`Symfony\\Component\\Workflow\\MarkingStore\\MarkingStoreInterface::setMarking` method.
253+
254+
An example of usage with the ``$context`` parameter can be when you need,
255+
in addition of marking your object in its new place, to contextualize this change.
256+
257+
.. tip::
258+
259+
Configure the ``type`` as ``method`` of the ``marking_store`` option to use this feature
260+
without implementing your own marking store.
261+
262+
You can also use this ``$context`` in your own marking store implementation.
263+
A simple implementation example is when you want to store the place as integer instead of string in your object.
264+
265+
Lets say your object has a status property, stored as an integer in your storage, and you want to log an optional
266+
comment any time the status changes::
267+
268+
// your own implementation class, to define in the configuration "marking_store"
269+
270+
class ObjectMarkingStore implements MarkingStoreInterface
271+
{
272+
public function getMarking($subject)
273+
{
274+
$subject->getStatus();
275+
// ...
276+
// return a marking
277+
}
278+
279+
public function setMarking($subject, Marking $marking, array $context);
280+
{
281+
// ...
282+
$subject->setStatus($newStatus, $context['log_comment'] ?? null);
283+
}
284+
}
285+
286+
// and in your Object class
287+
288+
public function getStatus()
289+
{
290+
return $this->status;
291+
}
292+
293+
public function setStatus(int $status, ?string $comment = null)
294+
{
295+
$this->status = $status;
296+
$this->addStatusLogRecord(new StatusLog($this, $comment));
297+
298+
return $this;
299+
}
300+
301+
// the StatusLog class can have a createdAt, a username,
302+
// the new status, and finally your optional comment retrieved from the workflow context.
303+
228304
Using Events
229305
------------
230306

0 commit comments

Comments
 (0)
0