Laravel Fsm Laravel Package

Getting Started

1. Install & configure: Run composer require christhompsontldr/laravel-fsm, then publish the config with php artisan vendor:publish --provider="Fsm\FsmServiceProvider" --tag="fsm-config". The default setup (using a status column and DB transactions) works out of the box.
2. Define your state enum: Create an enum implementing FsmStateEnum, e.g., enum OrderStatus implements FsmStateEnum { ... } — include a label() method for friendly display.
3. Register a definition: Place a class implementing FsmDefinition in app/Fsm/Definitions/. Use the FsmBuilder fluent API to declare states, transitions, and events.
4. Attach to your model: Add the HasFsm trait and implement transitions using $model->fsm()->trigger('pay'), .can(), .dryRun(), etc.

First use case: Enforce a strict order lifecycle (e.g., pending → paid → shipped → delivered) with guards preventing invalid operations.

Implementation Patterns

• State-based workflow enforcement: Encapsulate domain logic (e.g., “orders can only be cancelled before shipping”) directly in FSM definitions using .guard() closures or invocable classes — avoids scattered if conditions in controllers/services.
• Multi-column FSMs: For complex domains (e.g., Document models with approval_status and publication_status), define separate FsmBuilder chains per column and access them via $model->fsm('column_name').
• Async side-effects: Use queuedAction() for offloading non-critical post-transition work (e.g., sending notifications, analytics events) to jobs — keeps transitions synchronous and safe.
• Automatic diagram generation: Run php artisan fsm:diagram post-development to generate PlantUML visualizations of workflows for documentation or team review.
• Event-driven integrations: Listen on StateTransitioned events for audit logging, external sync (e.g., to CRM), or metrics — decouples logging from core business logic.
• Caching & performance: Define definitions once; the package auto-caches them. Use fsm:cache:clear and fsm:cache:rebuild in CI or deployment pipelines to maintain consistency.

Gotchas and Tips

• Enum strictness: Ensure your state enum always uses string backed types, and the DB column (status, etc.) stores the exact ->value. Mismatched types (e.g., int enums or non-backed enums) cause silent failures.
• Guards must be strict: Guards only allow transitions if they return true. A false or null return blocks the transition — return true explicitly if no custom validation is needed, or use closures for inline logic.
• Tracing transitions: Set 'log_failures' => true in config/fsm.php to capture failed transition attempts (e.g., guard rejections, invalid events) — invaluable for debugging workflow issues in production.
• fsm() state access: Calling $model->fsm() without args uses the default column (status). For multi-column FSMs, always specify the column: $model->fsm('column').
• State metadata: Use ->metadata([...]) on states for UI hints (e.g., colors, icons, badges), but remember it’s not persisted — regenerate it from enum logic or store in DB if required.
• Clear cache after refactoring: Changes to FsmDefinition classes require clearing the cache (php artisan fsm:cache:clear), or the old definition may persist — automate this in CI/deploy scripts.
• Dry-run safety: Prefer $model->fsm()->dryRun('event') before committing — returns full preview (from, to, can_transition) without mutations, great for audit or pre-check in forms.