Download the PHP package iotron/laravel-state-machine without Composer

Laravel State Machine

A robust, enum-aware state machine for Laravel Eloquent models. Define allowed transitions, validate before state changes, track full history, and prevent N+1 queries — all with native PHP BackedEnum support and zero dependencies beyond Laravel.

Features

• Native BackedEnum support — use enums everywhere, normalized internally
• N+1 query prevention — eager-load history, get zero-query lookups in loops
• Transaction-safe transitions — model save + history recording are atomic
• Lifecycle events — TransitionStarted, TransitionCompleted, TransitionFailed
• Validation hooks — block invalid transitions with Laravel Validator
• Before/after hooks — run closures on specific state changes
• Pending transitions — schedule future state changes with jobs
• History tracking — full audit trail with custom properties and changed attributes
• Safe auth resolution — no crashes in queue/CLI contexts
• Artisan generator — php artisan make:state-machine

Requirements

• PHP 8.2+
• Laravel 11 or 12

Installation

Publish the config file:

Publish and run the migrations:

Migrating from asantibanez/laravel-eloquent-state-machines? See the Migration Guide below — no database changes needed.

Quick Start

1. Create a State Machine

Define your transitions and default state:

2. Add the Trait to Your Model

3. Use It

Configuration

Defining State Machines

Transitions

The transitions() method returns a map of from => [allowed targets]:

Default State

Set the initial state for new models:

Record History

Control whether transitions are tracked (default: true):

Validation

Return a Validator to block transitions that don't meet requirements:

If the validator fails, a ValidationException is thrown and the model stays unchanged.

Before/After Hooks

Run closures when entering or leaving specific states. All hooks receive ($from, $to, $model):

State Proxy API

Calling $model->status() returns a State proxy with these methods:

All methods accept both strings and BackedEnum values.

N+1 Prevention

When you eager-load stateHistory, all history lookups use the in-memory collection — zero extra queries:

Without eager loading, each call falls back to a database query automatically.

Events

Three events fire during transitions for app-wide listening:

Pending Transitions

Schedule transitions to execute in the future:

Add the dispatcher job to your scheduler:

The job processes pending transitions in chunks and dispatches each as a separate queued job for reliability.

Transition Model

The Transition model (stored in the state_histories table by default) includes useful scopes:

Migrating from asantibanez/laravel-eloquent-state-machines

This package is a drop-in replacement. No database migration needed — it reads the same state_histories table by default.

Step 1: Install

Step 2: Update model imports

Step 3: Update state machine base class

Step 4: Update hook signatures

The old package used ($from, $model) / ($to, $model). This package uses a consistent ($from, $to, $model) for both before and after hooks:

Step 5: Remove old packages

Step 6: Enable native enum casts

You can now use Laravel's native enum cast — no more workarounds:

What's different?

Testing

Credits

This package is inspired by and built upon the work of asantibanez/laravel-eloquent-state-machines by Andrés Santibáñez. The original package provided the foundation for Eloquent state machine management that this package extends with native BackedEnum support, N+1 prevention, transaction safety, lifecycle events, and other improvements.

Changelog

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

License

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