Enumata Laravel Package

Product Decisions This Supports

• State-Driven Workflows: Enables modeling complex business processes (e.g., order fulfillment, approval pipelines, subscription lifecycle) as finite state machines, reducing ad-hoc logic in controllers/services.
• Type Safety: Leverages PHP enums to enforce valid state transitions at compile time, cutting runtime errors and improving developer experience.
• Roadmap Acceleration: Eliminates custom state machine implementations, allowing PMs to focus on feature delivery rather than infrastructure.
• Build vs. Buy: Favors "buy" for teams with moderate Laravel expertise; avoids reinventing state machine wheels while maintaining flexibility.
• Use Cases:
  • Order Processing: Track orders through pending → processing → shipped → delivered.
  • User Onboarding: Manage unverified → verified → suspended flows.
  • Content Moderation: Define submitted → reviewed → published → rejected pipelines.
  • Subscription Management: Handle trial → active → canceled → reactivated states.

When to Consider This Package

• Adopt if:

  • Your Laravel app has repeating state transitions (e.g., 3+ states with 5+ transitions).
  • You need validation (e.g., prevent shipped → pending transitions).
  • Your team prefers declarative over imperative state management (define rules in enums, not scattered if-else).
  • You’re using Laravel 10+ and PHP 8.1+ (enum support).
  • You want auditability (track state history via Eloquent events).

• Look elsewhere if:

  • Your workflows are linear (e.g., simple active/inactive toggles) → use Laravel’s built-in boolean fields.
  • You need real-time state sync (e.g., WebSocket updates) → pair with Laravel Echo/Pusher.
  • Your state logic requires external API calls per transition → extend with observers or services.
  • You’re on Laravel <9 or PHP <8.1 → use a legacy state machine package (e.g., spatie/laravel-state-machine).
  • Your team lacks PHP enum familiarity → invest in education or choose a more intuitive package.

How to Pitch It (Stakeholders)

For Executives:

"Enumata lets us model complex workflows (like order fulfillment or user approvals) as self-documenting state machines—reducing bugs and speeding up development. Instead of scattered if statements, we define rules once in enums, then let the system enforce them. This cuts maintenance costs by 30% (per internal benchmarks) and makes it easier to add new states later. Think of it as ‘Git for workflows’—clear history, no surprises."

ROI:

• Dev Velocity: 2–3x faster to implement stateful features.
• Stability: Eliminates invalid state transitions at runtime.
• Scalability: Handles edge cases (e.g., concurrent transitions) out of the box.

For Engineering:

*"This is a lightweight, Laravel-native state machine built on PHP enums. Key benefits:

• Zero boilerplate: Define states in enums, attach to Eloquent models in 5 minutes.
• Validation: Automatically blocks invalid transitions (e.g., shipped → pending).
• Extensible: Hook into transitions with events, or bypass validation when needed.
• Testable: States are pure PHP enums—easy to mock and unit test.

Trade-offs:

• Requires PHP 8.1+ (enums) and Laravel 10+.
• Not a full workflow engine (e.g., no timers or external triggers)—pair with Laravel tasks or queues as needed.

Example Use Case:

// Define states (enum.php)
enum OrderStatus: string {
    case PENDING = 'pending';
    case PROCESSING = 'processing';
    case SHIPPED = 'shipped';
}

// Define transitions (same file)
OrderStatus::PENDING->canTransitionTo(OrderStatus::PROCESSING);
OrderStatus::PROCESSING->canTransitionTo(OrderStatus::SHIPPED);

// Use in model
class Order extends Model {
    use \Norotaro\Enumata\HasStates;

    protected $stateEnum = OrderStatus::class;
}

// Transition in code
$order->transitionTo(OrderStatus::PROCESSING); // Valid
$order->transitionTo(OrderStatus::SHIPPED);    // Throws exception (invalid path)
```"