Download the PHP package lenderspender/laravel-state-transition-workflow without Composer

Laravel State Transitions Workflow

This package adds state transitions workflows to your Laravel models. Allowing you to specify transitions and how to act on those transitions.

To show you how to use this package, let's sketch the following scenario.

A transaction can have three states CREATED, FAILED and SUCCESS. When transitioning between states you probably want to act on this transition e.g. send a success email. You probably only want to allow transitions from SUCCESS to FAILED and not the other way around.

The transaction model would look like:

Here is what the TransactionState enum looks like:

And here is what the TransactionSuccessfullWorkflow could look like:

And here is how you use it:

Installation

You can install the package via composer:

Usage

The package provides a HasStateTransitions trait which you can use in any model where you want to support state.

State management

Registering state field

To setup states for the $status attribute you should add the HasStateTransitions trait to the model and implement the registerStateTransitions method.

Adding allowed transitions

Transitions are used to transition the state field for a model from one to another. You need to specify which transitions are allowed and what workflow should be started on transition. By default all transitions are not allowed, to allow transitions you should call allowTransition on the added state.

Single transition from State::FROM() to State::TO()

Allow transitions from State::CREATED() to State::FAILED() and State::SUCCESS()

Allow transitions from State::CREATED() and State::UPDATED() to State::FAILED() and State::SUCCESS()

Using transitions

Transitions can be used by calling the transitionStateTo method on the model.

By default the method uses the first registered state. When you've added multiple state fields you should specify which field to use.

When a state transitions is not allowed a LenderSpender\StateTransitionWorkflow\Exceptions\TransitionNotAllowedException is thrown.

Listing allowed state transitions

To know what allowed state transitions can be performed you could call the getAvailableStateTransitions on the model.

By default the method uses the first registered state. When you've added multiple state fields you should specify which field to use.

State workflows

When transitioning a model from one state to another you sometimes want to act on this transition. Or even prevent the transition from happening. That's where state workflows come into place.

Creating a workflow

Automatically handle the transition after workflow execution

Handle the transition in the workflow

Queuing transitions

When you want to perform some heavy actions before or after the transition you could queue the transition by implementing the ShouldQueue interface on the workflow.

Preventing transitions

Transitions can be prevented when you override the isAllowed method and return false in the workflow.

Registering a workflow to a state transition