Laravel Model States Laravel Package

Product Decisions This Supports

• Domain-Driven Design (DDD) Alignment: Enables explicit state modeling for complex business workflows (e.g., orders, subscriptions, payments) by encapsulating state logic in dedicated classes, improving code clarity and maintainability.
• State Machine Implementation: Facilitates transition rules (e.g., Pending → Paid but not Paid → Pending) without custom middleware or monolithic logic, reducing bugs and improving auditability.
• Build vs. Buy: Buy for teams needing state management without reinventing the wheel. Avoids technical debt from custom solutions while offering flexibility (e.g., PHP 8 attributes, custom events).
• Roadmap Priorities:
  • Phase 1: Adopt for high-impact models (e.g., Order, Subscription) with clear state transitions.
  • Phase 2: Extend to UI layers (e.g., dynamic styling/UX based on state, like the color() example).
  • Phase 3: Integrate with event-driven architectures (e.g., trigger webhooks or notifications on state changes).
• Use Cases:
  • Workflow Automation: Replace ad-hoc if-else checks (e.g., "Is this order shipped?") with declarative state transitions.
  • Data Integrity: Enforce constraints (e.g., "A Cancelled order cannot be Shipped") at the model level.
  • Analytics: Track state history (via StateChanged events) for reporting or debugging.
  • Multi-Tenant State Logic: Isolate state machines per tenant (e.g., different workflows for EU vs. US customers).

When to Consider This Package

• Adopt When:

  • Your models have 3+ distinct states with clear transition rules (e.g., Draft → Published → Archived).
  • You need type safety (e.g., IDE autocompletion for states) and runtime validation (e.g., block invalid transitions).
  • Your team prefers declarative over procedural logic (e.g., defining states in classes vs. hardcoding strings).
  • You’re using Laravel and want to avoid low-level state machine libraries (e.g., spatie/laravel-state-machine).
  • You need serialization/deserialization of states to/from the database (handled automatically).

• Look Elsewhere When:

  • States are simple (e.g., active/inactive flags) and don’t require transitions or complex logic.
  • You’re not using Laravel/Eloquent (package is tightly coupled to Laravel’s ORM).
  • Your state logic is highly dynamic (e.g., states change at runtime based on external APIs) and can’t be predefined in classes.
  • You need performance-critical state checks (this package adds minor overhead for serialization/validation).
  • Your team lacks familiarity with the State Pattern or State Machines (steepness of learning curve).

How to Pitch It (Stakeholders)

For Executives/Business Stakeholders

"This package lets us model complex business workflows (like orders or subscriptions) as self-documenting state machines, reducing errors and making rules easier to audit. For example, we can enforce that an order can’t be ‘shipped’ if it’s ‘cancelled’—without writing spaghetti code. It also unlocks features like dynamic UI updates (e.g., showing ‘green’ for ‘Paid’ orders) and better analytics by tracking state changes. The trade-off is minimal: a small upfront investment to standardize workflows across the codebase, with long-term gains in maintainability and scalability."

Key Outcomes:

• Fewer bugs from invalid state transitions.
• Faster onboarding for new devs (states are explicit in code).
• Enables future features like automated notifications or reporting.

For Engineering/Technical Stakeholders

*"This is a batteries-included solution for state management in Laravel, combining the State Pattern (encapsulate state-specific behavior) with State Machine rules (define allowed transitions). It’s ideal for:

• Complex workflows: E.g., Order states (Draft → Pending → Shipped → Delivered) with validation.
• Type safety: States are classes, not strings—IDE support and runtime checks included.
• Decoupling: State logic lives in separate classes, making tests and refactors easier.
• Laravel-native: Works seamlessly with Eloquent, casts, and events.

Why not build it ourselves?

• Avoids reinventing serialization/deserialization of states to DB.
• Already handles edge cases (e.g., custom state names, nested states).
• MIT-licensed, battle-tested (1.3K stars), and actively maintained.

Proposal:

1. Pilot: Adopt for 1–2 high-impact models (e.g., Subscription).
2. Standardize: Create a shared State base class and naming conventions.
3. Integrate: Hook into UI (e.g., state-based styling) and analytics (e.g., StateChanged events).
4. Document: Add a STATE_MANAGEMENT.md guide for the team."*

Alternatives Considered:

• Custom solution: Higher maintenance; misses features like transition validation.
• Other packages: spatie/laravel-state-machine is more rigid; this offers more flexibility (e.g., PHP 8 attributes, custom events).
• No change: Risk of ad-hoc state logic creeping into business logic, hurting testability.