Laravel Eloquent State Machines

Install the package via Composer and then publish the migrations to your application to set up the necessary database tables for state history tracking.

composer require asantibanez/laravel-eloquent-state-machines

php artisan vendor:publish --provider="Asantibanez\LaravelEloquentStateMachines\LaravelEloquentStateMachinesServiceProvider" --tag="migrations"

php artisan migrate

Create a new StateMachine class using the Artisan command: php artisan make:state-machine {Name}.

In the resulting class, you must implement:

• transitions(): Returns an array defining allowed state changes. You can use '*' as a wildcard for 'any state'.
• defaultState(): Returns the starting state for the model (can be null).
• recordHistory(): Returns true if you want the package to automatically log transitions in the state_histories table.

Example transition mapping:

public function transitions(): array
{
    return [
        'pending' => ['approved', 'declined'],
        'approved' => ['processed'],
    ];
}

php artisan make:state-machine StatusStateMachine

Use postponeTransitionTo to schedule a state transition for a later date instead of applying it immediately. This method saves the transition into a pending_transitions table.

Requirements

1. Parameters: Accepts the same parameters as transitionTo, plus a Carbon instance for the $when parameter.
2. Scheduler: You must schedule the PendingTransitionsDispatcher job in your Laravel scheduler (e.g., every minute) to process these transitions.

Checking Pending Transitions

Use hasPendingTransitions() on the state machine instance to check if a model has scheduled transitions.

Example Scheduler Setup:

$schedule->job(PendingTransitionsDispatcher::class)->everyMinute();

Example Usage:

$salesOrder->status()->postponeTransitionTo('approved', now()->addDays(1));

if ($salesOrder->status()->hasPendingTransitions()) {
    // ...
}

To attach a StateMachine to a model, use the HasStateMachines trait and define a public $stateMachines array. The keys in this array must match the database column names (fields) on your model.

use Asantibanez\
LaravelEloquentStateMachines\Traits\HasStateMachines;
use App\
StateMachines\StatusStateMachine;

class SalesOrder extends Model
{
    use HasStateMachines;

    public $stateMachines = [
        'status' => StatusStateMachine::class
    ];
}

The package requires two database tables to function: state_histories and pending_transitions. You can publish the migration stubs to your application's migration directory using the migrations tag.

php artisan vendor:publish --tag=migrations

When recordHistory() is enabled, the state machine records transitions in the state_histories table. You can inspect which model attributes changed during a specific transition using the following methods:

• changedAttributesNames(): Returns an array of attribute names that were modified during the transition.
• changedAttributeOldValue($attributeName): Returns the value of the attribute before the transition.
• changedAttributeNewValue($attributeName): Returns the value of the attribute after the transition.

$salesOrder = SalesOrder::create(['total' => 100]);
$salesOrder->total = 200;

$salesOrder->status()->transitionTo('approved');

$salesOrder->changedAttributesNames(); // ['total']
$salesOrder->changedAttributeOldValue('total'); // 100
$salesOrder->changedAttributeNewValue('total'); // 200

Once registered, the model provides a method named after the field (e.g., $model->status()) to manage transitions. Use transitionTo($to, $customProperties, $responsible) to move to a new state.

• $to: The target state name.
• $customProperties: (Optional) An associative array of data to store with the transition.
• $responsible: (Optional) The user/entity responsible for the change. Defaults to auth()->user().

If the transition is not defined in the StateMachine's transitions() method, a TransitionNotAllowed exception is thrown.

// Basic transition
$salesOrder->status()->transitionTo('approved');

// Transition with custom properties
$salesOrder->status()->transitionTo('approved', [
    'comments' => 'Customer has available credit',
]);

// Transition with a specific responsible user
$salesOrder->status()->transitionTo('approved', [], $responsible);

You can access data attached to the current state or historical states:

• getCustomProperty($key): Retrieves a custom property from the current state.
• snapshotWhen($state)->getCustomProperty($key): Retrieves a custom property from a previous state.
• responsible(): Retrieves the user/entity responsible for the current state.
• snapshotWhen($state)->responsible: Retrieves the user/entity responsible for a previous state.

// Current state
$salesOrder->status()->getCustomProperty('comments');
$salesOrder->status()->responsible();

// Historical state
$salesOrder->status()->snapshotWhen('approved')->getCustomProperty('comments');
$salesOrder->status()->snapshotWhen('approved')->responsible;