State Machine Laravel Package

Product Decisions This Supports

• Workflow Standardization: Enables consistent, auditable state transitions across domain objects (e.g., orders, subscriptions, approvals) by replacing ad-hoc conditional logic with a declarative graph. Reduces "works on my machine" bugs from inconsistent state checks.
• Build vs. Buy: Buy—avoids reinventing state management (e.g., no need to build a custom solution for workflows like draft → published → archived). MIT license and 500+ stars signal community trust.
• Use Cases:
  • Order Processing: Enforce pending → shipped → delivered with guards (e.g., "block ship if payment_failed").
  • User Lifecycle: trial → paid → cancelled with callbacks (e.g., send renewal reminders on paid).
  • Multi-Workflow Objects: Attach multiple state machines to a single entity (e.g., Invoice with payment_status and audit_status graphs).
  • Compliance: Log transitions via after callbacks to satisfy audit trails (e.g., GDPR, SOX).
• Roadmap Alignment:
  • Modularity: Integrates with Laravel/Symfony without locking into a monolith. Future-proof for PHP 8.3+ and Symfony 7/8.
  • Extensibility: Supports custom guards (e.g., RBAC) and event listeners (e.g., trigger analytics).
• Cost Savings: Reduces technical debt by centralizing state logic, cutting maintenance time for scattered if-else checks.

When to Consider This Package

• Adopt if:
  • Your domain has well-defined states and transitions (e.g., workflows, pipelines, lifecycles).
  • You need validation guards (e.g., "cannot cancel if confirmed") or side effects (e.g., send emails on shipped).
  • Your team prefers configuration over code (reduces cognitive load for complex workflows).
  • You’re using Laravel/Symfony and want a lightweight (~10KB) solution with no ORM dependency.
  • You require multiple state machines per object (e.g., Order with payment + shipping workflows).
• Look elsewhere if:
  • Your states are dynamic or unbounded (e.g., real-time systems with ad-hoc states).
  • You need event sourcing (consider Prooph).
  • Your stack is non-PHP (e.g., Node.js, Go).
  • You require visual state diagrams (tools like XState may fit better).
  • Your workflows are distributed (use event-driven architectures instead of in-memory state machines).

How to Pitch It (Stakeholders)

For Executives: *"This package eliminates workflow chaos by turning business rules (e.g., ‘orders can’t ship unless paid’) into configurable state machines. Instead of scattered if-else checks, we define transitions once and enforce them everywhere. For example:

• Orders: pending → shipped → delivered with automatic validation.
• Users: trial → paid → cancelled with email triggers.
• Compliance: Audit trails via callbacks for GDPR/SOX.

It’s lightweight, open-source, and integrates with our Laravel stack—no new infrastructure needed. Think of it as guardrails for our processes with zero dev overhead."*

For Engineers: *"winzou/state-machine lets us declare workflows instead of embedding them in business logic. Key perks:

• Guards: Block invalid transitions (e.g., cancel if confirmed).
• Callbacks: Hook into before/after transitions (e.g., send Slack alerts, log actions).
• Multi-Graph Support: Attach multiple state machines to one object (e.g., Order with payment + shipping workflows).
• Zero ORM Dependency: Pure PHP, no database coupling—just store the state field in your model.
• Laravel/Symfony Ready: Works standalone or via StateMachineBundle.

Example:

// Define an order workflow:
$config = [
    'states' => ['pending', 'shipped', 'delivered', 'cancelled'],
    'transitions' => [
        'ship' => ['from' => 'pending', 'to' => 'shipped'],
        'cancel' => ['from' => ['pending', 'shipped'], 'to' => 'cancelled'],
    ],
    'callbacks' => [
        'guard' => [
            'block-ship' => [
                'from' => 'pending',
                'do' => fn(Order $order) => !$order->payment->is_paid(),
            ],
        ],
        'after' => [
            'notify-shipped' => [
                'on' => 'ship',
                'do' => fn(Order $order) => $order->sendShippingEmail(),
            ],
        ],
    ],
];

Why not DIY?

• Maintenance: Actively updated (last release: 2026-03-24).
• Battle-tested: 500+ stars, used in production (e.g., Symfony ecosystem).
• Performance: Micro-optimized for PHP (~10KB). No external dependencies beyond PHP core.

Trade-offs:

• No built-in history: You’ll need to log transitions manually (e.g., via after callbacks).
• Pre-1.0: Versioning is 0.x, but MIT license and active contributions reduce risk.
• Callback overhead: Each transition may trigger multiple callbacks—optimize for high-throughput systems if needed."*