Laravel Fsm Laravel Package

Product Decisions This Supports

• Workflow Automation: Enables structured state transitions for complex business processes (e.g., order fulfillment, content moderation, user onboarding) without custom logic sprawl.
• Build vs. Buy: Eliminates the need to build a custom FSM solution, reducing technical debt and accelerating development.
• Auditability & Compliance: Built-in logging and event-driven architecture support regulatory requirements (e.g., tracking order status changes for financial systems).
• Scalability: Supports multiple independent FSMs per model (e.g., approval_status and publication_status for documents).
• Roadmap Prioritization:
  • Short-term: Quickly implement workflows for MVP features (e.g., order status, user verification).
  • Long-term: Extend to critical paths (e.g., payment processing, multi-step approvals) with guards/actions/callbacks.
• Use Cases:
  • E-commerce: Order lifecycle (cart → checkout → shipped → delivered).
  • SaaS: User roles (trial → paid → suspended).
  • Content Platforms: Article states (draft → reviewed → published → archived).

When to Consider This Package

• Adopt When:

  • Your application has stateful entities with clear, linear/non-linear transitions (e.g., orders, tickets, documents).
  • You need validation guards (e.g., "Only transition to shipped if payment is confirmed").
  • Audit trails are required for compliance or debugging (logging is built-in).
  • You’re using Laravel 12.x and want zero-config integration.
  • Your team lacks FSM expertise but needs robust workflows.

• Look Elsewhere If:

  • Your workflows are highly dynamic (e.g., real-time multiplayer games) where runtime state changes dominate.
  • You need distributed FSMs (this package is single-process; consider Event Sourcing for microservices).
  • Your states are not enum-based (e.g., free-form strings with no validation).
  • You require visual design tools (this package generates diagrams but doesn’t integrate with tools like Camunda).
  • Your team prefers TypeScript/React for workflows (consider XState for frontend-heavy apps).

How to Pitch It (Stakeholders)

For Executives:

"This package lets us model complex business processes—like order fulfillment or content approvals—as structured workflows, reducing bugs and speeding up development. For example, instead of scattered if-else logic for order statuses, we define rules once (e.g., 'paid' → 'shipped' only if payment is verified) and let the system enforce them. It also adds automatic audit logs for compliance, cutting manual tracking work by 50%. We’re using it first for [high-impact feature], with a roadmap to roll it out across [other critical areas]."

ROI:

• Dev Velocity: 30% faster to implement workflows vs. custom code.
• Stability: Guards prevent invalid state transitions (e.g., no "shipped" orders without payment).
• Auditability: Built-in logs replace ad-hoc tracking systems.

For Engineers:

*"This is a batteries-included FSM for Laravel that handles:

• State validation: Prevent invalid transitions (e.g., draft → published without review).
• Actions/Callbacks: Run jobs, send notifications, or update related models during transitions.
• Guards: Add custom logic (e.g., 'Only cancel if order is <24h old').
• Multiple FSMs: One model can have independent workflows (e.g., approval_status + publication_status).
• Events: Hook into TransitionAttempted/TransitionFailed for observability.

Why not build it?

• Maintenance: We’d spend 20+ hours building guards/actions from scratch.
• Testing: Pre-built test coverage and Laravel integration save QA time.
• Future-proof: Supports queued actions, caching, and extensibility.

Example Use Case:

// Replace this:
if ($order->status === 'paid' && $order->payment_verified) {
    $order->status = 'shipped';
    $order->save();
    SendShippingLabel::dispatch($order);
}

// With this:
$order->fsm()->trigger('ship'); // Handles validation, actions, and events automatically.
```"

**Migration Path**:
1. **Pilot**: Use for a non-critical workflow (e.g., user verification).
2. **Expand**: Roll out to high-risk areas (e.g., payment processing).
3. **Standardize**: Enforce FSM for all new stateful models.