gtt / workflow-extensions-bundle
Bundle for extended workflow management and automation
Installs: 1 408
Dependents: 0
Suggesters: 0
Security: 0
Stars: 40
Watchers: 11
Forks: 4
Open Issues: 2
Type:symfony-bundle
Requires
- php: >=5.5.9
- symfony/expression-language: ^3.0
- symfony/framework-bundle: ^3.2
- symfony/workflow: ^3.2
Requires (Dev)
- doctrine/doctrine-bundle: ~1.0
- doctrine/doctrine-fixtures-bundle: ^2.2
- doctrine/orm: ^2.4.8
- jms/job-queue-bundle: ^1.3.0
- nesbot/carbon: ^1.21
- phpunit/phpunit: ~4.0
- symfony/browser-kit: ^3.0
- symfony/monolog-bundle: ^3.0
- symfony/property-access: ^3.0
Suggests
- doctrine/doctrine-bundle: Required for OrmPersistentMarkingStore usage
- jms/job-queue-bundle: Needed for workflow transitions scheduling
- nesbot/carbon: Needed for workflow transitions scheduling
- symfony/console: Needed for workflow transitions scheduling
This package is auto-updated.
Last update: 2024-10-08 00:54:01 UTC
README
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:
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:
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.
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:
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:
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:
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:
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:
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)" context: doctrine: ~
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:
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: ~ context: access_checker: ~
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.
Contexts
When expressions use some container service it is fetched from container using container.get()
method. Since Symfony 4
private services can not be fetched from container in such way. To access required service inside the expression the
former must be explicitly exposed in bundle configuration. This is done inside context
array in bundle
configuration:
workflow_extensions: ... context: # This will expose "doctrine" service from DI under "doctrine" alias inside expression container doctrine: ~ # This will expose "security.authorization_checker" from DI and make it available under # "auth_checker" alias inside expression container auth_checker: 'security.authorization_checker' workflows: simple: guard: expression: 'not container.get("auth_checker").isGranted("ROLE_USER")' transitions: dangerous: 'not container.get("auth_checker").isGranted("ROLE_MANAGER")'
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.