8000 Documentation workflow · symfony/symfony-docs@3fa0a6e · GitHub
[go: up one dir, main page]
Skip to content

Commit 3fa0a6e

Browse files
noniagriconomienoniagriconomie
committed
Documentation workflow
1 parent 3675000 commit 3fa0a6e

File tree

4 files changed

+102
-5
lines changed

4 files changed

+102
-5
lines changed

‎contributing/documentation/overview.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -270,6 +270,8 @@ purposes following these steps:
270270
271271
The generated documentation is available in the ``_build/html`` directory.
272272

273+
You can also use Docker tha wraps all this for you, please go read https://github.com/symfony/symfony-docs#docker
274+
273275
Frequently Asked Questions
274276
--------------------------
275277

‎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 object's position in the workflow. This is the goal of the
12+
**marking store** that writes to a property of the object 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+
You can also directly inject the proper :class:`Symfony\\Component\\Workflow\\StateMachine`
220+
service automatically created by Symfony for you ``state_machine.pull_request``::
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: 70 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'
4747
arguments:
4848
- 'currentPlace'
4949
supports:
@@ -127,7 +127,7 @@ like this:
127127
'enabled' => true
128128
),
129129
'marking_store' => array(
130-
'type' => 'multiple_state', // or 'single_state'
130+
'type' => 'multiple_state', // or 'single_state', 'method'
131131
'arguments' => array('currentPlace')
132132
),
133133
'supports' => array('App\Entity\BlogPost'),
@@ -167,7 +167,7 @@ like this:
167167
168168
.. note::
169169

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

@@ -221,6 +221,16 @@ you can get the workflow by injecting the Workflow registry service::
221221
// ... if the transition is not allowed
222222
}
223223

224+
// Update the currentState on the post passing some contextual data
225+
// to the whole workflow process
226+
try {
227+
$workflow->apply($post, 'publish', [
228+
'log_comment' => 'My logging comment for the publish transition.'
229+
]);
230+
} catch (TransitionException $exception) {
231+
// ... if the transition is not allowed
232+
}
233+
224234
// See all the available transitions for the post in the current state
225235
$transitions = $workflow->getEnabledTransitions($post);
226236
}
@@ -234,6 +244,63 @@ you can get the workflow by injecting the Workflow registry service::
234244
The :method:`Symfony\\Component\\Workflow\\Registry::all` method was
235245
introduced in Symfony 4.1.
236246

247+
.. versionadded:: 4.3
248+
The :method:`Symfony\\Component\\Workflow\\Workflow::apply` has now a new parameter ``$context``
249+
that is passed to the :class:`Symfony\\Component\\Workflow\\MarkingStore\\MarkingStoreInterface`
250+
:method:`Symfony\\Component\\Workflow\\MarkingStore\\MarkingStoreInterface::setMarking` method.
251+
252+
An example of usage with the ``$context`` parameter can be when you need, in addition of marking your object
253+
in its new place, to contextualize this change.
254+
255+
.. tip::
256+
257+
Configure the ``type`` as ``method`` of the ``marking_store`` option to use this feature
258+
without implementing your own marking store.
259+
260+
You can also use this ``$context`` in your own marking store implementation.
261+
A simple implementation example is when you want to store the place as integer instead of string in your object.
262+
263+
Lets say your object has a status property, stored as an integer in your storage, and you want to log an optional
264+
comment any time the status changes.
265+
266+
.. code-block:: php
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 retrived from the workflow context.
303+
237304
Using Events
238305
------------
239306

0 commit comments

Comments
 (0)
0