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

Commit 9dfef16

Browse files
noniagriconomienoniagriconomie
committed
Documentation workflow
1 parent 3675000 commit 9dfef16

File tree

4 files changed

+104
-5
lines changed

4 files changed

+104
-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 that wraps all this for you, please visit 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, or somewhere else, the current **place(s)**
13+
to remember.
1314

1415
.. note::
1516

‎workflow/state-machines.rst

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -209,6 +209,35 @@ 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+
224+
// ...
225+
use Symfony\Component\Workflow\StateMachine;
226+
227+
class SomeService
228+
{
229+
private $stateMachine;
230+
231+
public function __construct(StateMachine $stateMachine)
232+
{
233+
$this->stateMachine = $stateMachine;
234+
}
235+
236+
public function someMethod($subject)
237+
{
238+
$this->stateMachine->apply($subject, 'wait_for_review', [
239+
'log_comment' => 'My logging comment for the wait for review transition.'
240+
]);
212241
// ...
213242
}
214243

‎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