State Machine Bundle Laravel Package

Product Decisions This Supports

• Workflow Automation: Enables structured, rule-based state transitions for domain entities (e.g., order processing, content moderation, approval pipelines). Reduces hard-coded conditional logic in business logic layers.
• Decoupled Business Rules: Centralizes state transition logic in YAML/JSON configs, making it easier to modify workflows without code changes (e.g., adjusting approval flows for new compliance requirements).
• Build vs. Buy: Buy—avoids reinventing state machine logic (e.g., no need to build custom validation or callback systems). Lightweight alternative to heavier frameworks like Symfony Workflow.
• Use Cases:
  • Content Moderation: Article/publish workflows (e.g., draft → review → publish).
  • E-Commerce: Order states (pending → shipped → delivered).
  • Access Control: User role transitions (pending → approved → suspended).
  • Audit Trails: Log transitions for compliance (e.g., submitted → rejected → appealed).
• Roadmap Alignment: Supports incremental adoption (start with simple workflows, expand to complex ones). Compatible with Symfony’s ecosystem (e.g., integrates with services for callbacks).

When to Consider This Package

• Adopt If:

  • Your domain requires explicit state transitions with clear rules (e.g., "only move from pending_review to published if approved").
  • You need guard clauses (e.g., "block transition if validation fails") or pre/post-transition actions (e.g., send emails, update metadata).
  • Your team prefers declarative configs over procedural logic for workflows.
  • You’re using Symfony (or PHP with minimal setup) and want a lightweight solution.
  • You need debugging tools (e.g., SM\Debug\DebugCommand for Symfony CLI).

• Look Elsewhere If:

  • You need real-time event-driven workflows (consider Event Sourcing or Kafka-based systems).
  • Your state machine requires distributed coordination (e.g., multi-service sagas—use Temporal or Camunda).
  • You’re not using Symfony (though the core library is framework-agnostic, the bundle is Symfony-specific).
  • You need visual workflow editors (e.g., Camunda, Zeebe).
  • Your workflows are highly dynamic (e.g., user-defined states at runtime—consider a graph database like Neo4j).

How to Pitch It (Stakeholders)

For Executives:

"This package lets us define workflows (e.g., content approvals, order processing) in simple configs instead of scattered code. It reduces bugs from hard-coded state logic, makes workflows easier to update, and integrates seamlessly with our Symfony stack. For example, we could cut content moderation delays by 30% by automating state transitions and notifications—all without rewriting business logic."

Key Benefits:

• Faster Iterations: Change workflows via config (e.g., add a new approval step) without deployments.
• Auditability: Clear logs of state changes for compliance.
• Scalability: Handles simple to complex workflows without performance overhead.

For Engineers:

*"This is a battle-tested, lightweight state machine for Symfony that replaces messy if-else chains with declarative YAML configs. Key features:

• Guard Callbacks: Block invalid transitions (e.g., reject publish if content is flagged).
• Pre/Post Actions: Trigger services (e.g., send emails, update analytics) on state changes.
• Debugging: Built-in Symfony command to inspect valid transitions.
• Zero Lock-in: MIT-licensed, no vendor lock-in.

Example Use Case: Replace this:

if ($article->state === 'pending_review' && $reviewer->isApproved()) {
    $article->state = 'published';
    $this->emailService->send($article);
}

With this (config-driven):

transitions:
  publish:
    from: [pending_review]
    to: published
callbacks:
  after:
    email_on_publish:
      on: publish
      do: ['@email_service', 'send']
      args: ['object']

Why Not Build It?

• Already handles edge cases (e.g., circular transitions, invalid states).
• Actively maintained (Symfony 7+ support, 300+ stars).
• Integrates with Symfony’s DI and service container."**