Skip to content

Commit 57cfedb

Browse files
stewartmalikjaviereguiluz
stewartmalik
authored and
javiereguiluz
committed
[Workflow] Choose which Workflow events should be dispatched
1 parent ff65542 commit 57cfedb

File tree

1 file changed

+159
-10
lines changed

1 file changed

+159
-10
lines changed

‎workflow.rst

+159-10
Original file line numberDiff line numberDiff line change
@@ -351,14 +351,6 @@ order:
351351
* ``workflow.[workflow name].announce``
352352
* ``workflow.[workflow name].announce.[transition name]``
353353

354-
You can avoid triggering those events by using the context::
355-
356-
$workflow->apply($subject, $transitionName, [Workflow::DISABLE_ANNOUNCE_EVENT => true]);
357-
358-
.. versionadded:: 5.1
359-
360-
The ``Workflow::DISABLE_ANNOUNCE_EVENT`` constant was introduced in Symfony 5.1.
361-
362354
.. note::
363355

364356
The leaving and entering events are triggered even for transitions that stay
@@ -452,6 +444,163 @@ missing a title::
452444

453445
The optional second argument of ``setBlocked()`` was introduced in Symfony 5.1.
454446

447+
Choosing which Events to Dispatch
448+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
449+
450+
.. versionadded:: 5.2
451+
452+
Ability to choose which events to dispatch was introduced in Symfony 5.2.
453+
454+
You are able to specify which events (does not apply to Guard event) will be
455+
fired when performing each transition by passing an array of workflow events
456+
to the ``events_to_dispatch`` configuration option.
457+
458+
Valid options for ``events_to_dispatch`` are:
459+
460+
* ``null`` - all events are dispatched
461+
* ``[]`` - no events are dispatched
462+
* ``['workflow.leave', 'workflow.completed']`` - only specific events are dispatched
463+
464+
.. note::
465+
466+
Guard Events are still dispatched in all instances.
467+
468+
.. configuration-block::
469+
470+
.. code-block:: yaml
471+
472+
# config/packages/workflow.yaml
473+
framework:
474+
workflows:
475+
blog_publishing:
476+
# ...
477+
events_to_dispatch: ['workflow.leave', 'workflow.completed']
478+
# ...
479+
480+
.. code-block:: xml
481+
482+
<!-- config/packages/workflow.xml -->
483+
<?xml version="1.0" encoding="UTF-8" ?>
484+
<container xmlns="http://symfony.com/schema/dic/services"
485+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
486+
xmlns:framework="http://symfony.com/schema/dic/symfony"
487+
xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd
488+
http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
489+
>
490+
<framework:config>
491+
<framework:workflow name="blog_publishing">
492+
<!-- ... -->
493+
<framework:event-to-dispatch>workflow.leave</framework:event-to-dispatch>
494+
<framework:event-to-dispatch>workflow.completed</framework:event-to-dispatch>
495+
<!-- ... -->
496+
</framework:workflow>
497+
</framework:config>
498+
</container>
499+
500+
.. code-block:: php
501+
502+
// config/packages/workflow.php
503+
$container->loadFromExtension('framework', [
504+
// ...
505+
'workflows' => [
506+
'blog_publishing' => [
507+
// ...
508+
'events_to_dispatch' => [
509+
'workflow.leave',
510+
'workflow.completed',
511+
],
512+
// ...
513+
],
514+
],
515+
]);
516+
517+
To specify that no events will be dispatched pass an empty array to the
518+
configuration option.
519+
520+
.. configuration-block::
521+
522+
.. code-block:: yaml
523+
524+
# config/packages/workflow.yaml
525+
framework:
526+
workflows:
527+
blog_publishing:
528+
# ...
529+
events_to_dispatch: []
530+
# ...
531+
532+
.. code-block:: xml
533+
534+
<!-- config/packages/workflow.xml -->
535+
<?xml version="1.0" encoding="UTF-8" ?>
536+
<container xmlns="http://symfony.com/schema/dic/services"
537+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
538+
xmlns:framework="http://symfony.com/schema/dic/symfony"
539+
xsi:schemaLocation="http://symfony.com/schema/dic/services
540+
https://symfony.com/schema/dic/services/services-1.0.xsd
541+
http://symfony.com/schema/dic/symfony
542+
https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
543+
<framework:config>
544+
<framework:workflow name="blog_publishing">
545+
<!-- ... -->
546+
<framework:event-to-dispatch></framework:event-to-dispatch>
547+
<!-- ... -->
548+
</framework:workflow>
549+
</framework:config>
550+
</container>
551+
552+
.. code-block:: php
553+
554+
// config/packages/workflow.php
555+
$container->loadFromExtension('framework', [
556+
// ...
557+
'workflows' => [
558+
'blog_publishing' => [
559+
// ...
560+
'events_to_dispatch' => [],
561+
// ...
562+
],
563+
],
564+
]);
565+
566+
You are also able to explicitly disable a specific event from being fired
567+
when applying a transition::
568+
569+
use App\Entity\BlogPost;
570+
use Symfony\Component\Workflow\Exception\LogicException;
571+
572+
$post = new BlogPost();
573+
574+
$workflow = $this->container->get('workflow.blog_publishing');
575+
576+
try {
577+
$workflow->apply($post, 'to_review', [
578+
Workflow::DISABLE_ANNOUNCE_EVENT => true,
579+
Workflow::DISABLE_LEAVE_EVENT => true,
580+
]);
581+
} catch (LogicException $exception) {
582+
// ...
583+
}
584+
585+
Choosing to disable an event for a specific transition will take precedence
586+
over any events specified in the workflow configuration. In the above example
587+
the ``workflow.leave`` event will not be fired, even if it has been specified
588+
as an event to be dispatched for all transitions in the workflow configuration.
589+
590+
.. versionadded:: 5.1
591+
592+
The ``Workflow::DISABLE_ANNOUNCE_EVENT`` constant was introduced in Symfony 5.1.
593+
594+
.. versionadded:: 5.2
595+
596+
The constants for other events (as seen below) were introduced in Symfony 5.2.
597+
598+
* ``Workflow::DISABLE_LEAVE_EVENT``
599+
* ``Workflow::DISABLE_TRANSITION_EVENT``
600+
* ``Workflow::DISABLE_ENTER_EVENT``
601+
* ``Workflow::DISABLE_ENTERED_EVENT``
602+
* ``Workflow::DISABLE_COMPLETED_EVENT``
603+
455604
Event Methods
456605
~~~~~~~~~~~~~
457606

@@ -665,7 +814,7 @@ of domain logic in your templates:
665814

666815
``workflow_has_marked_place()``
667816
Returns ``true`` if the marking of the given object has the given state.
668-
817+
669818
``workflow_transition_blockers()``
670819
Returns :class:`Symfony\\Component\\Workflow\\TransitionBlockerList` for the given transition.
671820

@@ -700,7 +849,7 @@ The following example shows these functions in action:
700849
{% if 'reviewed' in workflow_marked_places(post) %}
701850
<span class="label">Reviewed</span>
702851
{% endif %}
703-
852+
704853
{# Loop through the transition blockers #}
705854
{% for blocker in workflow_transition_blockers(post, 'publish') %}
706855
<span class="error">{{ blocker.message }}</span>

0 commit comments

Comments
 (0)