- What is sebdesign/laravel-state-machine and how does it work with Laravel?
- It is a thin Laravel integration layer over Symfony Workflow, not its own state engine. It registers a service provider, resolves machines from configuration, and provides a trait for Eloquent models so you can define states, transitions, and guards. The package validates transitions, fires events, and throws clear exceptions when a move is illegal.
- How do I install and set up the package in a Laravel app?
- Install it with composer require sebdesign/laravel-state-machine, publish the config, and define your graphs, states, and transitions in configuration. Apply the package trait to the Eloquent models that own a lifecycle, then call the machine to apply a transition. A pilot on one entity is usually small because most of the work is domain modelling rather than plumbing.
- How do I define states and transitions for an Eloquent model?
- States and transitions are declared in the published configuration rather than scattered through controllers. You map a graph or state machine to a model, list its states, and define allowed transitions between them. The trait then exposes transitions against model records so the configured rules are enforced consistently.
- How do guards work and can I add custom validation or authorisation?
- Guards are checks that must pass before a transition is allowed, so they are the natural place for policy or authorisation logic. The package supports guard and transition classes, which keeps business rules out of controllers. If a guard fails, the transition is rejected with a clear exception rather than silently changing state.
- Does the package fire events when a state transition happens?
- Yes, it integrates with Laravel's event system so you can listen for transition events and run side effects such as notifications or queued jobs. You can also listen to the underlying Symfony Workflow events. This keeps lifecycle reactions decoupled from the code that performs the transition.
- Does it support Laravel 13 and which PHP and Symfony Workflow versions are supported?
- Version 3.4.7 added a Laravel 13.x compatibility contribution from laravel-shift, which widened the illuminate constraints so Laravel 13 upgrades are not blocked. The notes do not confirm whether Laravel 13 is CI-verified or merely permitted by composer.json, so check the test matrix before relying on it. The tested PHP floor and supported symfony/workflow range should also be confirmed from the repository's composer.json and CI config for your target release.
- Does the package store transition history or an audit log?
- No, transition history and audit logging are consumer-owned; the package does not persist them for you. If you need an audit trail, record transitions in your own table by listening to transition events. You should also decide how to store the current state column on the model and how to backfill existing records.
- How does it handle concurrent transitions on the same record?
- Concurrent transitions are not serialised automatically, so two requests could race on the same aggregate. You must own row-level locking or optimistic concurrency on the state column, for example with a version column or a SELECT FOR UPDATE inside a transaction. Treat idempotency and illegal-state prevention as domain design responsibilities, not something the package guarantees.
- How does this compare with using Symfony Workflow directly or simple status enums?
- Using Symfony Workflow directly gives the same mature engine but leaves you to wire up Laravel service-provider, config, and Eloquent trait integration yourself. This package concentrates its value in that glue code, so it is convenient but tracks both Symfony Workflow and Laravel API stability. Simple status enums plus scattered if checks are lighter at first but tend to smear lifecycle rules across the codebase as the domain grows.
- Is the package actively maintained and what are the main production risks?
- It is effectively a small-maintainer package with corporate-adjacent contributions, so treat it as a dependency with a bus factor and pin versions rather than floating. The architecture risk is moderate-low because the underlying Symfony Workflow component is mature and widely deployed. The main production risks are untested constraint widening, version-coupling lag between Laravel and Symfony majors, and transition design errors such as incomplete guards or non-idempotent transitions.