Download the PHP package codewiser/workflow without Composer
On this page you can find all versions of the php package codewiser/workflow. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download codewiser/workflow
More information about codewiser/workflow
Files in codewiser/workflow
Informations about the package workflow
Workflow
- Setup
- Consistency
- Authorization
- Chargeable Transitions
- Business Logic
- Disabling Transitions
- Removing Transitions
- User Provided Data
- Translations
- JSON
- Events
- EventListener
- Callback
- Log Transitions
Package provides workflow functionality to Eloquent Models.
Workflow is a sequence of states, document evolve through. Transitions between states inflicts the evolution road.
Setup
First, describe the workflow blueprint with available states and transitions:
You may use
Enum
instead of scalar values.
Next, include trait and create method to bind a blueprint to model's attribute.
That's it.
Consistency
Workflow observes Model and keeps state machine consistency healthy.
State and Transition objects
In an example above we describe blueprint with scalar values, but actually they will be transformed to the objects. Those objects bring some additional functionality to the states and transitions, such as caption translations, transit authorization, routing rules, pre- and post-transition callbacks etc...
Authorization
As model's actions are not allowed to any user, as changing state is not allowed to any user. You may define transition authorization rules either using Policy
or using callable
.
Using Policy
Provide ability name. Package will examine given ability against associated model.
Using Closure
Authorization Closure may return true
or false
, or throw AuthorizationException
.
Authorized Transitions
To get only transitions, authorized to the current user, use authorized
method of TransitionCollection
:
Authorizing Transition
When accepting user request, do not forget to authorize workflow state changing.
Chargeable Transitions
Chargeable transition will fire only then accumulates some charge. For example, we may want to publish an article only then at least three editors will accept it.
Charge
class has more options, that allows to provide vote statistics or prevent to vote twice.
Business Logic
Disabling transitions
Transition may have some prerequisites to a model. If model fits this conditions then the transition is possible.
Prerequisite is a callable
with Model
argument. It may throw an exception.
To temporarily disable transition, prerequisite should throw a TransitionRecoverableException
. Leave helping instructions in exception message.
Here is an example of issues user may resolve.
User will see the problematic transitions in a list of available transitions. User follows instructions to resolve the issue and then may try to perform the transition again.
Removing transitions
In some cases workflow routes may divide into branches. Way to go forced by business logic, not user. User even shouldn't know about other ways.
To completely remove transition from a list, prerequisite should throw a TransitionFatalException
.
User will see only one possible transition depending on order amount value.
Additional Context
Sometimes application requires an additional context to perform a transition. For example, it may be a reason the article was rejected by the reviewer.
First, declare validation rules in transition or state definition:
Next, set the context in the controller.
When creating a model:
When transiting model:
The context will be validated while saving, and you may catch a ValidationException
.
After all you may handle this context in events.
Translations
You may define State
and Transition
objects with translatable caption.
Then using Enums you may implement \Codewiser\Workflow\Contracts\StateEnum
to enum
.
Transition
without caption will inherit caption from its target State
.
Additional Attributes
Sometimes we need to add some additional attributes to the workflow states and transitions. For example, we may group states by levels and use this information to color states and transitions in user interface. Then using Enums you may implement \Codewiser\Workflow\Contracts\StateEnum
to enum
.
Transition
inherits attributes from its target State
.
Json Serialization
For user to interact with model's workflow we should pass the data to a frontend of the application:
The payload will be like that:
Events
State Callback
You may define state callback(s), that will be called then state is reached.
Callback is a callable
with Model
and optional Transition
arguments.
Transition Callback
You may define transition callback(s), that will be called after transition were successfully performed.
It is absolutely the same as State Callback.
You may define few callbacks to a single transition.
EventListener
Transition generates ModelTransited
event. You may define EventListener
to listen to it.
Transition History
The Package may log transitions to database table.
Register \Codewiser\Workflow\WorkflowServiceProvider
in providers
section of config/app.php
.
Add workflow.history
into config/services.php
:
Publish and run migrations:
php artisan vendor:publish --tag=workflow-migrations
php artisan migrate
It's done.
To get historical records, add \Codewiser\Workflow\Traits\HasTransitionHistory
to Model
with workflow. It brings transitions
relation.
Historical records presented by \Codewiser\Workflow\Models\TransitionHistory
model, that holds information about transition performer, source and target states and a context, if it were provided.
Blueprint Validation
The Package may validate Workflow Blueprint that you defined.
Register \Codewiser\Workflow\WorkflowServiceProvider
in providers
section of config/app.php
.
Run console command with blueprint classname:
php artisan workflow:blueprint --class=App/Workflow/ArticleWorkflow