ringierimu / state-workflow
Laravel State Workflow provide tools for defining and managing workflows and activities with ease.
Installs: 19 942
Dependents: 0
Suggesters: 0
Security: 0
Stars: 33
Watchers: 17
Forks: 10
Open Issues: 2
Requires
- php: ^7.3|^8.0
- illuminate/events: ^7|^8|^9|^10.0
- illuminate/support: ^7|^8|^9|^10.0
- symfony/event-dispatcher: ^5.1
- symfony/property-access: ^5.1
- symfony/workflow: ^5.1
Requires (Dev)
- funkjedi/composer-include-files: ^1.0
- laravel/legacy-factories: ^1.1
- mockery/mockery: ^1.3|^1.4.2
- orchestra/database: ^5|^6|^7
- orchestra/testbench: ^5|^6|^7|^8.0
- phpunit/phpunit: ^8|^9
This package is auto-updated.
Last update: 2024-10-09 14:28:10 UTC
README
Laravel State workflow provide tools for defining and managing workflows and activities with ease. It offers an object oriented way to define a process or a life cycle that your object goes through. Each step or stage in the process is called a state. You do also define transitions that describe the action to get from one state to another.
A workflow consist of state and actions to get from one state to another. These actions are called transitions which describes how to get from one state to another.
Installation
$ composer require ringierimu/state-workflow
Publish config/workflow.php
file
$ php artisan vendor:publish --provider="Ringierimu\StateWorkflow\StateWorkflowServiceProvider"
Run migrations
$ php artisan migrate
Configuration
- Open
config/workflow.php
and configure it
// this should be your model name in camelcase. eg. PropertyListing::Class => propertyListing 'post' => [ // class of your domain object 'class' => \App\Post::class, // Register subscriber for this workflow which contains business rules. Uncomment line below to register subscriber //'subscriber' => \App\Listeners\UserEventSubscriber::class, // property of your object holding the actual state (default is "current_state") //'property_path' => 'current_state', //uncomment this line to override default value // list of all possible states 'states' => [ 'new', 'pending_activation', 'activated', 'deleted', 'blocked' ], // list of all possible transitions 'transitions' => [ 'create' => [ 'from' => ['new'], 'to' => 'pending_activation', ], 'activate' => [ 'from' => ['pending_activation'], 'to' => 'activated', ], 'block' => [ 'from' => ['pending_activation', 'activated'], 'to' => 'blocked' ], 'delete' => [ 'from' => ['pending_activation', 'activated', 'blocked'], 'to' => 'deleted', ], ], ],
- Add
HasWorkflowTrait
to your model class to support workflow
<?php namespace App; use Illuminate\Database\Eloquent\Model; use Ringierimu\StateWorkflow\Traits\HasWorkflowTrait; /** * Class Post * @package App */ class Post extends Model { use HasWorkflowTrait; /** * The attributes that are mass assignable. * * @var array */ protected $fillable = [ ..., 'current_state', // If not using default attribute, update this to match value in workflow.php ] }
Usage
Manage State/Workflow
<?php use App\Post; $post = new Post(); //Apply transition $post->applyTransition("create"); $post = $post->refresh(); //Return current_state value $post->state(); //pending_activation //Check if this transition is allowed $post->canTransition("activate"); // True //Return Model state history $post->stateHistory();
Authenticated User Resolver
Ability to audit and track who action a specific state change for your object. The package leverage the default Laravel auth provider to resolve the authenticated user when applying the state changes.
For a custom authentication mechanism, you should override authenticatedUserId
in your object class with your own implementation.
/** * Return authenticated user id. * * @return int|null */ public function authenticatedUserId() { // Implement authenticated user resolver }
Fired Event
Each step has three events that are fired in order:
- An event for every workflow
- An event for the workflow concerned
- An event for the workflow concerned with the specific transition or state name
During state/workflow transition, the following events are fired in the following order:
- Validate whether the transition is allowed at all.
Their event listeners are invoked every time a call to
workflow()->can()
,workflow()->apply()
orworkflow()->getEnabledTransitions()
is executed.Guard Event
workflow.guard workflow.[workflow name].guard workflow.[workflow name].guard.[transition name]
- The subject is about to leave a state.
Leave Event
workflow.leave workflow.[workflow name].leave workflow.[workflow name].leave.[state name]
- The subject is going through this transition.
Transition Event
workflow.transition workflow.[workflow name].transition workflow.[workflow name].transition.[transition name]
- The subject is about to enter a new state.
This event is triggered just before the subject states are updated.
Enter Event
workflow.enter workflow.[workflow name].enter workflow.[workflow name].enter.[state name]
- The subject has entered in the states and is updated.
Entered Event
workflow.entered workflow.[workflow name].entered workflow.[workflow name].entered.[state name]
- The subject has completed this transition.
Completed Event
workflow.completed workflow.[workflow name].completed workflow.[workflow name].completed.[transition name]
Subscriber
Create subscriber class to listen to those events and the class should extends WorkflowSubscriberHandler
.
To register method to listen to specific even within subscriber use the following format for method name:
- on[Event] -
onGuard()
- on[Event][Transition/State name] -
onGuardActivate()
NB:
- Method name must start with
on
key word otherwise it will be ignored. Subscriber
class must be register insideworkflow.php
config file with the appropriate workflow configuration.Subscriber
class must extendsWorkflowSubscriberHandler
.Guard
,Transition
andCompleted
Event uses of transition name.Leave
,Enter
andEntered
Event uses state name.
<?php namespace App\Listeners; use Ringierimu\StateWorkflow\Events\EnteredEvent; use Ringierimu\StateWorkflow\Events\EnterEvent; use Ringierimu\StateWorkflow\Events\GuardEvent; use Ringierimu\StateWorkflow\Events\LeaveEvent; use Ringierimu\StateWorkflow\Events\TransitionEvent; use Ringierimu\StateWorkflow\Subscribers\WorkflowSubscriberHandler; /** * Class PostEventSubscriber * @package App\Listeners */ class UserEventSubscriber extends WorkflowSubscriberHandler { /** * Handle workflow guard events. * * @param GuardEvent $event */ public function onGuardActivate($event) { $user = $event->getOriginalEvent()->getSubject(); if (empty($user->dob)) { // Users with no dob should not be allowed $event->getOriginalEvent()->setBlocked(true); } } /** * Handle workflow leave event. * * @param LeaveEvent $event */ public function onLeavePendingActivation($event) { } /** * Handle workflow transition event. * * @param TransitionEvent $event */ public function onTransitionActivate($event) { } /** * Handle workflow enter event. * * @param EnterEvent $event */ public function onEnterActivated($event) { } /** * Handle workflow entered event. * * @param EnteredEvent $event */ public function onEnteredActivated($event) { } }
Event Methods
Each workflow event has an instance of Event
. This means that each event has access to the following information:
getOriginalEvent()
: Returns the Parent Event that dispatched the event which has the following children methods:getSubject()
: Returns the object that dispatches the event.getTransition()
: Returns the Transition that dispatches the event.getWorkflowName()
: Returns a string with the name of the workflow that triggered the event.isBlocked()
: Returns true/false if transition is blocked.setBlocked()
: Sets the blocked value.
Artisan Command
Symfony workflow uses GraphvizDumper to create the workflow image by using the dot
command.
The dot
command is part of Graphviz.
You will be required to download dot
command to make use of this command.
https://graphviz.gitlab.io/download/
Usage
php artisan workflow:dump workflow_name
Run Unit Test
composer test