10000 [WiP] Document Workflow 4.3 changes by pbowyer · Pull Request #11211 · symfony/symfony-docs · GitHub
[go: up one dir, main page]

Skip to content

[WiP] Document Workflow 4.3 changes #11211

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Document 4.3 marking_store changes. Have reservations from a DX per…
  • Loading branch information
pbowyer committed Apr 7, 2019
commit e1c0e04057941dbf25ce1ed3672661b1c9d88ed6
178 changes: 17 additions & 161 deletions workflow/usage.rst
10000
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,9 @@ like this:
audit_trail:
enabled: true
marking_store:
type: 'multiple_state' # one of 'single_state', 'multiple_state', 'method'
type: 'method'
arguments:
- false
- 'currentPlace'
supports:
- App\Entity\BlogPost
Expand All @@ -68,7 +69,7 @@ like this:
.. code-block:: xml

<!-- config/packages/workflow.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<?xml version="1.0" encoding="utf-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
Expand All @@ -80,7 +81,8 @@ like this:
<framework:workflow name="blog_publishing" type="workflow">
<framework:audit-trail enabled="true"/>

<framework:marking-store type="single_state">
<framework:marking-store type="method">
<framework:argument>false</framework:argument>
<framework:argument>currentPlace</framework:argument>
</framework:marking-store>

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't use XML config, can someone please provide the initial_places code for it.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be nice to add it in the code doc.
Here is the final ref

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe I've done this correctly!

Expand Down Expand Up @@ -117,6 +119,7 @@ like this:
.. code-block:: php

// config/packages/workflow.php

$container->loadFromExtension('framework', [
// ...
'workflows' => [
Expand All @@ -126,8 +129,11 @@ like this:
'enabled' => true
],
'marking_store' => [
'type' => 'multiple_state', // one of 'single_state', 'multiple_state', 'method'
'arguments' => ['currentPlace'],
'type' => 'method',
'arguments' => [
false,
'currentPlace',
],
],
'supports' => ['App\Entity\BlogPost'],
'places' => [
Expand Down Expand Up @@ -166,18 +172,14 @@ As configured, the following property is used by the marking store::

.. note::

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

versionadded:: 4.3

The ``method`` marking store type was introduced in Symfony 4.3.
The Workflow Component supports workflows that can be in one or multiple places
(states) at the same time. To restrict a workflow to a single state, set the first
argument to ``true`` when defining the ``marking_store``.

.. tip::

The ``type`` (default value ``single_state``) and ``arguments`` (default
value ``marking``) attributes of the ``marking_store`` option are optional.
The ``type`` (default value ``method``) and ``arguments`` (default
values ``false`` and ``marking``) attributes of the ``marking_store`` option are optional.
If omitted, their default values will be used.

.. tip::
Expand Down Expand Up @@ -224,90 +226,11 @@ you can get the workflow by injecting the Workflow registry service::
// ... if the transition is not allowed
}

// Update the currentState on the post passing some contextual data
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why do you remove this one?

// to the whole workflow process
try {
$workflow->apply($post, 'publish', [
'log_comment' => 'My logging comment for the publish transition.',
]);
} catch (TransitionException $exception) {
// ... if the transition is not allowed
}

// See all the available transitions for the post in the current state
$transitions = $workflow->getEnabledTransitions($post);
}
}

.. versionadded:: 4.1

The :class:`Symfony\\Component\\Workflow\\Exception\\TransitionException`
class was introduced in Symfony 4.1.

.. versionadded:: 4.1

The :method:`Symfony\\Component\\Workflow\\Registry::all` method was
introduced in Symfony 4.1.

You can pass some context as the second argument of the ``apply()`` method.
This can be useful when the subject not only needs to apply a transition,
but for example you also want to log the context in which the switch happened.

This context is forwarded to the :method:`Symfony\\Component\\Workflow\\MarkingStore\\MarkingStoreInterface::setMarking`
method of the marking store.

.. versionadded:: 4.3

The ``$context`` argument of the :method:`Symfony\\Component\\Workflow\\Workflow::apply`
method was introduced in Symfony 4.3.

.. tip::

Configure the ``type`` as ``method`` of the ``marking_store`` option to use this feature
without implementing your own marking store.

You can also use this ``$context`` in your own marking store implementation.
A simple implementation example is when you want to store the place as integer instead of string in your object.

Lets say your object has a status property, stored as an integer in your storage, and you want to log an optional
comment any time the status changes::

// your own implementation class, to define in the configuration "marking_store"

class ObjectMarkingStore implements MarkingStoreInterface
{
public function getMarking($subject)
{
$subject->getStatus();
// ...
// return a marking
}

public function setMarking($subject, Marking $marking, array $context);
{
// ...
$subject->setStatus($newStatus, $context['log_comment'] ?? null);
}
}

// and in your Object class

public function getStatus()
{
return $this->status;
}

public function setStatus(int $status, ?string $comment = null)
{
$this->status = $status;
$this->addStatusLogRecord(new StatusLog($this, $comment));

return $this;
}

// the StatusLog class can have a createdAt, a username,
// the new status, and finally your optional comment retrieved from the workflow context.

Using Events
------------

Expand Down Expand Up @@ -455,7 +378,7 @@ See example to make sure no blog post without title is moved to "review"::
{
public function guardReview(GuardEvent $event)
{
/** @var App\Entity\BlogPost $post */
/** @var \App\Entity\BlogPost $post */
$post = $event->getSubject();
$title = $post->title;

Expand Down Expand Up @@ -549,70 +472,3 @@ The following example shows these functions in action:
{% if 'waiting_some_approval' in workflow_marked_places(post) %}
<span class="label">PENDING</span>
{% endif %}

Transition Blockers
-------------------

.. versionadded:: 4.1

Transition Blockers were introduced in Symfony 4.1.

Transition Blockers provide a way to return a human-readable message for why a
transition was blocked::

use Symfony\Component\Workflow\Event\GuardEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class BlogPostPublishListener implements EventSubscriberInterface
{
public function guardPublish(GuardEvent $event)
{
/** @var \App\Entity\BlogPost $post */
$post = $event->getSubject();

// If it's after 9pm, prevent publication
if (date('H') > 21) {
$event->addTransitionBlocker(
new TransitionBlocker(
"You can not publish this blog post because it's too late. Try again tomorrow morning."
)
);
}
}

public static function getSubscribedEvents()
{
return [
'workflow.blogpost.guard.publish' => ['guardPublish'],
];
}
}

You can access the message from a Twig template as follows:

.. code-block:: html+twig

<h2>Publication was blocked because:</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>

Don't need a human-readable message? You can still use::

$event->setBlocked('true');
0