Developed with love by KnpLabs Hire us for your project!
0

workflow-extensions-bundle

by GlobalTradingTechnologies

Bundle for extended workflow management and automation

WorkflowExtensionsBundle

Build Status
Coverage Status
Scrutinizer Code Quality
Latest Stable Version
Latest Unstable Version
License

Original Symfony 3 Workflow component and the part of Symfony's FrameworkBundle that
integrates it in Symfony's ecosystem state explicit declaring all the things as a main concept.
This means that if you need to apply workflow transition you must find target workflow object and call $workflow->apply() inside your business logic code.
Another example: if you want to block transition you must create a listener that subscribes to GuardEvent and decide whether to block or
allow transition inside.

But sometimes workflow processes are complex and the code handles transition management grows quickly.

WorkflowExtensionsBundle provides extensions and additional features to original Symfony 3 Workflow component that can help you to automate some actions you must do manually when you deal with workflow component out of the box:

  1. Event-based transitions triggering

  2. Event-based transitions scheduling

  3. Configurable transition blocking

Requirements

Since Symfony's Workflow component requires PHP 5.5.9+ WorkflowExtensionsBundle supports PHP 5.5.9 and newer.

Workflow component is integrated in Symfony 3 ecosystem starting from 3.2 version. In order to use it in applications based on Symfony 3.1 and lower you can use 1.x version of the Bundle.

Besides symfony/framework-bundle and symfony/expression-language packages are required.

Installation

Bundle should be installed via composer

composer require gtt/workflow-extensions-bundle

After that you need to register the bundle inside your application kernel:
php
public function registerBundles()
{
$bundles = array(
// ...
new \Gtt\Bundle\WorkflowExtensionsBundle\WorkflowExtensionsBundle(),
);
}

Configuration and Usage

Workflow subjects

First of all you need to tell WorkflowExtensionsBundle what kind of workflow subjects you want it to deal with.
List it inside subject_manipulator section.
yml
workflow_extensions:
subject_manipulator:
My\Bundle\Entity\Order: ~
My\Bundle\Entity\Claim: ~

Logging

Since all the things WorkflowExtensionsBundle does are basically automated (and even asynchronous) it is reasonable
to log important aspects in details. All the WorkflowExtensionsBundle subsystems log (when it is possible) workflow name, subject class and subject id during execution.

There is one non-trivial thing here: how to retrieve subject id from subject. More often subject id can be fetched by invoking getId() method, - in this case you have nothing to do.
Otherwise (when your subject class has no getId() method or there is the other one should be used to get subject's identifier) you need to specify expression to get subject identifier. This expression will be evaluated by ExpressionLanguage component with subject variable that represents subject object:
yaml
workflow_extensions:
subject_manipulator:
My\Bundle\Entity\Order: ~
My\Bundle\Entity\Claim:
id_from_subject: 'subject.getCustomId()'

Event-based transitions processing

One of the most important use cases of WorkflowExtensionsBundle is to execute some workflow manipulations as a reaction to the particular system events. Any Symfony's Event instance can play the role of such firing event.
In order to subscribe workflow processing to such an event you should start with config like this:
yaml
workflow_extensions:
workflows:
simple:
triggers:
event:
some.event:
...
another.event:
...
complex:
triggers:
event:
some.event:
...
third.event:
...
...

This config firstly specifies target workflow name (simple) that should be equal to one of defined workflows in symfony/framework-bundle or fduch/workflow-bundle config.
For each workflow then you define target event and configure processing details as described in sections below.

Event-based transitions triggering

WorkflowExtensionsBundle makes possible to trigger workflow transitions when particular event is fired.
For example if you want to trigger transition to_processing when workflow subject (My\Bundle\Entity\Order instance) is created (order_created.event is fired) the WorkflowExtensionsBundle's config can look like this:

yaml
workflow_extensions:
workflows:
simple:
triggers:
event:
order_created.event:
actions:
apply_transition:
- [to_processing]
subject_retrieving_expression: 'event.getOrder()'
subject_manipulator:
My\Bundle\Entity\Order: ~

In example above subject_retrieving_expression section contains expression (it will be evaluated by ExpressionLanguage) used to retrieve workflow subject.
Since expression language that evaluates these expressions has container variable (represents DI Container) enabled you can construct more complicated things for example like this here: "container.get('doctrine').getEntityMangerForClass('My\\\\Bundle\\\\Entity\\\\Order').find('My\\\\Bundle\\\\Entity\\\\Order', event.getId())" (Lot of backslashes is set due to specialty of expression language syntax).

You can also specify more then one transition to be tried to perform when event is fired by using apply_transitions construction like this:
yaml
apply_transitions:
- [[to_processing, closing]]

In this case (by default) the first applicable transition would be applied.
You can also consequentially try to apply several transitions without breaking execution after first successfully applied transition using ability to
invoke apply_transition action several times in line with different arguments:
yaml
apply_transition:
- [to_processing]
- [closing]

Event-based transitions scheduling

Events can be used not only to immediately apply transitions, - you can also schedule it with specified offset.
WorkflowExtensionsBundle uses jms/job-queue-bundle as a scheduler engine.
Imagine you need to apply transition set_problematic that places workflow subject Order into state "Problematic" if it is not correctly processed in 30 days.
Such goal can be achieved using config like this:

workflow_extensions:
    workflows:
        simple:
            triggers:
                event:
                    order_created.event:
                        schedule:
                            apply_transition:
                                -
                                    arguments: [closing]
                                    offset: P30D
                        subject_retrieving_expression: 'event.getOrder()'
    scheduler: ~                
    subject_manipulator:
        My\Bundle\Entity\Order:
            subject_from_domain: "container.get('doctrine').getManagerForClass(subjectClass).find(subjectClass, subjectId)"

Configuration above is similar to previous one with several differences.

The first difference is that actions is replaced with schedule key to tell the engine that actions below should be executed deferred.

The second difference is each action's arguments are defined now under explicit arguments key (which is automatically set under the hood for simple triggering thanks to configuration normalization rules and also can be set explicitly there) and
offset key that defines time interval (according to ISO-8601) started from the moment when corresponding trigger event occurred and after that scheduled transition should be applied.

The third difference is that you need to configure scheduler section to activate scheduler engine. Also it can be used to set particular entity manager to persist scheduler jobs.

The fourth difference is that you must configure under subject_manipulator's subject_from_domain key expression (it will be evaluated by ExpressionLanguage) that will be used to retrieve workflow subject when scheduled transition will be tried to be applied.
The subjectClass (for example My\Bundle\Entity\Order) and subjectId (i.e. identifier you can use to fetch the object) are the expression variables here. Moreover you can use DI container here again since it also registered as expression variable.

Another feature here is that if you have frequent repeatable event that schedules transition then for the first time when event is fired transition would be simply scheduled and next event occurrences will just reset scheduler countdown to restart it from current moment.
This behaviour can be very useful when you need continuously delay particular transition until specific event is fired regularly. You should not configure something specific to achieve this since this feature is enabled by default.

Transition blocking

Basically you can prevent transition from applying explicitly by listening special GuardEvent and call its setBlocked method inside. With the help of WorkflowExtensionsBundle you can automate things again.
For example if you to block all the transitions invoked by non-ROLE_USER users and allow only managers (ROLE_MANAGER holders) to apply dangerous transition you should use config like this:
yaml
workflow_extensions:
workflows:
simple:
guard:
expression: 'not container.get("access_checker").isGranted("ROLE_USER")'
transitions:
dangerous: 'not container.get("access_checker").isGranted("ROLE_MANAGER")'
subject_manipulator:
My\Bundle\Entity\Order: ~

Note that here again we use expression evaluated by ExpressionLanguage with container variable represents DI Container allowing usage of public services to decide whether to block transitions or not.

Tests

WorkflowExtensionsBundle is covered by unit and functional tests. Functional tests can probably make more clear how the bundle works if you have some misunderstanding.

The MIT License (MIT)

Copyright (c) 2015 GlobalTradingTechnologies

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.