Laravel State Machines

State machines with Spatie Model States for complex state transitions and validation.

Core Concept

state-management.md – State machine patterns:

• Spatie Model States setup
• State classes with behavior
• Transition classes with validation
• State-specific methods
• When to use state machines vs simple enums
• Testing state transitions

Pattern

// State classes
final class DraftOrderState extends OrderState
{
    public function canBeSubmitted(): bool
    {
        return true;
    }
}

final class PendingOrderState extends OrderState
{
    public function canBeSubmitted(): bool
    {
        return false;
    }
}

// Transition class
final class SubmitOrderTransition extends Transition
{
    public function handle(): OrderState
    {
        // Validation and side effects

        return new PendingOrderState($this->order);
    }
}

// Usage
$order->status->transitionTo(PendingOrderState::class);

Use state machines for complex state with validation, side effects, or state-specific behavior. Use simple enums for basic status fields.