- How do I install and set up Laravel FSM in a Laravel 12 project?
- Install via Composer with `composer require christhompsontldr/laravel-fsm`, publish the config if needed, and define your states using PHP 8.1 enums. The package auto-discovers FSM definitions via service providers, so no manual registration is required. Start by adding the `HasFsm` trait to your model and defining transitions in a fluent builder class.
- Can I use Laravel FSM for complex workflows like order processing with branching paths?
- Yes, Laravel FSM supports branching workflows with guards and actions. For example, you can define conditional transitions (e.g., `paid → shipped` or `paid → refunded`) using custom guard logic. The fluent API lets you chain transitions and validate each path independently, making it ideal for multi-step processes like order fulfillment.
- Does Laravel FSM work with Laravel’s event system and queues?
- Absolutely. The package emits `StateTransitioned` and `TransitionFailed` events, which integrate seamlessly with Laravel’s event listeners and queues. You can also queue actions (e.g., `queuedAction`) to defer side effects like sending emails or updating external systems, ensuring non-blocking transitions.
- How do I handle concurrent state transitions (e.g., race conditions in payment processing)?
- Laravel FSM uses database transactions by default to ensure atomic transitions. For high-concurrency scenarios, you can add application-level locks (e.g., `pessimisticLock`) in your guards or actions. The package also supports dry runs for testing, helping you validate transition logic before deployment.
- Can I log state transitions to a database or external system?
- Yes, the package includes built-in logging for audit trails. By default, transitions are logged to the Laravel log, but you can customize the storage (e.g., database, ELK, or third-party services) by extending the `StateTransitionLogger` interface. The logs include timestamps, user context, and transition details for full traceability.
- What Laravel versions and PHP requirements does this package support?
- Laravel FSM is designed for Laravel 12.x and requires PHP 8.1+. It leverages PHP 8.1+ enums for type safety and integrates with Laravel’s latest features. The package is backward-compatible within minor updates, so upgrading between Laravel 12.x versions should be smooth.
- How do I test state transitions without affecting production data?
- Use the `dryRun` method to simulate transitions without committing changes to the database. This is perfect for unit and feature tests. You can also mock guards and actions to isolate logic and verify behavior. The package’s fluent API makes it easy to assert expected states and transition paths in your tests.
- Can I define multiple state machines for a single model (e.g., approval_status and publication_status)?
- Yes, Laravel FSM supports multiple state machines per model by defining separate FSM builders for each column. For example, a `Document` model could have one FSM for `approval_status` (draft → reviewed → approved) and another for `publication_status` (unpublished → published). Each FSM operates independently on its designated column.
- What are the performance implications of using guards and actions in transitions?
- Guards and actions add minimal overhead since they’re executed only during transitions. The package caches FSM definitions to avoid repeated parsing, and you can disable logging if audit trails aren’t critical. For performance-critical paths, ensure guards and actions are idempotent and avoid heavy operations like external API calls—offload such work to queues or background jobs.
- Are there alternatives to Laravel FSM for simpler state management needs?
- For basic state management, you might consider Laravel’s built-in enums or simple database columns with validation rules. However, Laravel FSM shines when you need guards, actions, logging, or multiple state machines. If you’re already using an event-driven architecture, this package integrates natively, reducing boilerplate compared to rolling your own solution.