timatanga / workflow
The timatanga Workflow package. Manages classes/objects workflow state
Requires
- php: ^8.0
- psr/event-dispatcher: ^1.0
- timatanga/events: dev-master
Requires (Dev)
- phpunit/phpunit: 10.0.x-dev
- symfony/var-dumper: 6.0.x-dev
This package is auto-updated.
Last update: 2025-04-29 01:22:47 UTC
README
The Workflow module provides capabilites for managing a workflow. This package is heavily inspired by Symfony Workflow component with some specific extensions like:
- instead if guarding a transition by event, condition callbacks allow for more control
- listeners allow for automated transitions
Installation
composer require dbisapps/workflow
Registration
n a Laravel application's config/app.php configuration file, the providers option defines a list of service providers that should be loaded by Laravel. When someone installs your package, you will typically want your service provider to be included in this list. Instead of requiring users to manually add your service provider to the list, auto discovery is enabled by this packages.
Class/Object Configuration
To enable a class or object for workflow management some configurations are required:
-
implements WorkflowStoreInterface
-
uses HasWorkflow trait
class Subject implements WorkflowStoreInterface { use HasWorkflow; }
Configuration with Configuration File
For usage in a Laravel application, the config/workflow.php can be used to provide workflow configurations. Please refer to the tests directory, Config.php for an workflow configuration example.
Then the path to the configuration file can be passed into the registry class constructor.
$registry = new Registry(config_path('workflow.php'));
Configuration without Configuration File
Building a worklow registry can be done without a configuration file.
// create registry instance
$registry = new Registry;
// create event dispatcher which is optional but required for events, listeners
$dispatcher = new EventDispatcher;
// build transitions
$transitions = [];
$transitions[] = new Transition('t1', 'a', 'b');
$transitions[] = new Transition('t2', 'b', 'c');
// build workflow definition
$definition = new Definition([
'name' => 'workflow name',
'states' => range('a', 'c'),
'initial' => 'a',
'transitions' => $transitions,
]);
// add workflow and its supported class/object to registry
$registry->addWorkflow(new Workflow($definition, $dispatcher), Subject::class);
Basic Usage
// retrieve workflow for subject by accessing registry.
$workflow = $registry->get(new Subject());
// when more than one workflow is assigned to subject, the specific workflow must be named
$workflow = $registry->get(new Subject(), 'workflow name');
// retrieve array of enabled transitions, that are applicable on current state and conditions
$transitions = $workflow->enabledTransitions($subject);
// retrieve array of blocked transitions as TransitionBlocker
$blocked = $workflow->blockedTransitions($subject);
// evaluate if transition is allowed on subjects current state
$can = $workflow->can($subject, 't2')
// apply a transition on subject, supress events (optional). New state/states are returned
$state = $workflow->apply($subject, 't2', [Workflow::LEAVE])
Transition Events
Several events are fired before, during and after the transition. Applying an event dispatcher it's possible to hook into the events: Leave > Transition > Enter > (change state) > Entered Subjects state is changed after enter and befored entered.
Dispatched events can be limited
in workflow configuration file:
return [
'workflow name' => [
'supports' => Subject::class,
...
'events' => [Workflow::ENTER_LEAVE, Workflow::ENTER_EVENT],
]
in workflow definition:
return new Definition([
'name' => 'workflow name',
...
'events' => [Workfow::LEAVE_EVENT, Workflow::ENTERED]
]);
while applying a transition:
$state = $workflow->apply($subject, 't2', [Workfow::LEAVE_EVENT, Workflow::ENTERED])
Transition Conditions
If conditions are assigned to a transition, they all must be fulfilled before the transition is allowed to fire. Conditions can be configured upfront in the workflow configuration or during runtime.
// build a condition
$fn = new Condition('blocked', function($subject) { return $subject->blocked == false; });
// extend a workflow transition with additional condition
$workflow->extend('t2', $fn );
// remove condition from transition
$workflow->reduce('t2', $fn );
Transition Listeners
Imagine to have an invoice workflow which has arrived in the latest state. While the latest state is reached a payment workflow should be started and payment instance should be persisted in database. This requirement needs some kind of connection between different workflows.
This is where transition listeners come into play. While listening for an event, a workflow transition can be triggered automatically. Basically this is possible within a workflow but also between different workflows.
// create a callback function
$cb = function($event) { $event->getWorkflow()->apply($event->getSubject(), 't2'); };
// create a listener, when worklfow A has entered state completed, invoke callback
$listener = new Listener('workflow.workflow_A.entered.completed', $cb);
// configure listener in workflow definition
$definitionB = new Definition([
'name' => 'workflow_B',
...
'listeners' => $listener,
]);
// create workflows, with shared event dispatcher
$eventDispatcher = new EventDispatcher;
$workflowA = new Workflow($definitionA, $eventDispatcher);
$workflowB = new Workflow($definitionB, $eventDispatcher);
// apply transition t2 on subjectA
$subjectA = new Subject();
$states = $workflowA->apply($subjectA, 't2');
// the result of the listener callback can be accessed by listener method
// in this case, a new subject has been created
$subjectB = $listener->result();
Context Model
---------- ---------
CONTROLS Condition Condition
---------- ---------
v v
------------ ------------ ------------
PROCESS x---------- State ------------ State ------------ State
^ ------------ ^ ------------ ^ ------------
| | |
| |
TRANSITION O O
|
|
LISTENER O
^ ^ ^
---------- ---------- ----------
RESOURCE Subject Subject Subject
---------- ---------- ----------
Registry Workflows must be assigned to supported classes/objects. These assignments are stored
in the workflow registry.
Workflow A workflow manages transitions between states of a supported class/object. It therefor
contains workflow definitions and capabilities like event dispatcher or logger.
Definition Workflow configurations are provides as definitions, like
- name workflow name
- states states of the workflow
- initial initial state of the workflow
- transitions transitions between states
- events events to dispatch, null to dispatch all events
- listeners listeners to automate transitions
State State of a workflow. A state is also called as place.
Transition A Transitions defines the source (froms) and destination (tos) states.
In case of multiple source destinations all must be met before a transition can be applied.
Multiple destination states are allowed to be transitioned at once,
Conditions Conditions are logical rules (boolean) which must be fulfilled before a transition can take place.
A condition normaly is related to its subject attributes.
Listener Listeners extend workflow capabilites to allow for automated transitions.
State changes are firing events and can trigger subsequent transitions without user interactions.