# Laravel State Machines

> State machines using Spatie Model States for complex state transitions. Use when implementing or modifying state machines, transitions, or transition validation.

- Skill: `leeovery/laravel-state-machines` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add leeovery/laravel-state-machines`
- Raw SKILL.md: https://api.skillmd.com/api/skills/leeovery/laravel-state-machines/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: leeovery (https://skillmd.com/u/leeovery)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/leeovery/laravel-state-machines

---


# Laravel State Machines

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

## Core Concept

**[state-management.md](references/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

```php
// 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.