Download the PHP package soap/eloquent-workflow without Composer

Simple states and transitions workflow for Laravel Eloquent

This package add state transition workflow to eloquent model. User can choose to take action from available transitions, makes eloquent model to transit from one state to another state. It is based on lots of work from codewiser/workflow

Support us

Installation

You can install the package via composer:

You can publish and run the migrations with:

You can publish the config file with:

This is the contents of the published config file:

Optionally, you can publish the views using

Usage

• Setup
• Consistency
• Authorization
• 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 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:

Using Closure

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.

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 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 definition:

Next, set the transition context in the controller:

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.

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.

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 context arguments.

Transition Callback

You may define transition callback(s), that will be called after transition were successfully performed.

Callback is a callable with Model and context arguments.

You may define few callbacks to a single transition.

EventListener

Transition generates ModelTransited event. You may define EventListener to listen to it.

Transition Logs

The Package may log transitions to database table.

Register \Soap\EloquentWorkflow\EloquentWorkflowServiceProvider in providers section of config/app.php.

Run migrations:

php artisan migrate

Edit workflow.logging into config/eloquent-workflow.php:

It's done.

To get logging records, add \Soap\EloquentWorkflow\Traits\HasTransitionLog to Model with workflow. It brings transitions relation.

Historical records presented by \Soap\EloquentWorkflow\Models\TransitionLog 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 \Soap\EloquentWorkflow\WorkflowServiceProvider in providers section of config/app.php.

Run console command with blueprint classname:

php artisan workflow:blueprint --class=App/Workflow/ArticleWorkflow

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Prasit Gebsaap
• All Contributors

License

The MIT License (MIT). Please see License File for more information.