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

Laravel State Machine

Declarative state machines for Eloquent models. Define the states a model can be in and the transitions between them, and let the package guarantee that only valid transitions ever happen — with guards, events and an optional audit trail.

Quick start

Define a machine:

Bind it to a model attribute:

Use it:

Why a state machine instead of if statements

The state of an order, a subscription, a support ticket or a KYC request is rarely a free-form string: it's a set of named states with strict rules about which one can follow which. Encoding those rules as scattered if ($order->status === 'paid') checks means the rules live in a dozen places and nothing prevents an invalid jump like pending → delivered.

A state machine puts the rules in a single declaration and enforces them:

• Invalid transitions can't happen. Applying a transition from the wrong state throws an exception instead of silently corrupting your data.
• Guards gate transitions on business rules. "You can't ship without an address" becomes a guard, not a code review comment.
• Every change emits an event. Hook side effects (send the receipt, notify the warehouse) onto StateTransitioned instead of hunting down every setter.
• You get an audit trail for free. The optional history records who moved what, from where, to where and when.

The handler API

$model->stateMachine($attribute) returns a handler. With a single machine the attribute is optional.

The context array passed to apply() reaches the guards and the dispatched events, and is stored alongside the history row.

Guards

A guard is a closure that receives the model and the context array. The transition is only allowed when it returns true.

can() returns false when a guard blocks it; apply() throws GuardFailedException.

Transition effects (atomic)

Attach a side effect to a transition with ->using(). It runs inside the same database transaction as the state change and the history record, so everything is all-or-nothing: if the effect throws an exception, the state never moves.

If payment->refund() throws an exception, the transition is rolled back — the order stays in paid, no history row is written and the in-memory model is restored. No half-applied transitions.

Diagram

Render any machine as a Mermaid state diagram:

Paste the output into a bash php artisan vendor:publish --tag=state-machine-migrations php artisan migrate env STATE_MACHINE_HISTORY=true bash composer install composer test

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## Security

Please review the [security policy](SECURITY.md) before reporting a
vulnerability.

## License

The MIT License (MIT). See [LICENSE](LICENSE).