- How do I install iben12/laravel-statable?
- It is a Composer package installable with composer require iben12/laravel-statable under the MIT license. After installation you add the package trait to the Eloquent model, then declare the allowed states and transitions on that model. There is no external engine or extra infrastructure to run, so adoption is a small footprint change. Run a quick spike in a sandbox against your exact PHP and Laravel versions before committing.
- Does laravel-statable support Laravel 10 and Laravel 11?
- There is no stated support for Laravel 10 or 11 in the package's documented claims, and the last release was in July 2021. Because Eloquent internals change across major versions, compatibility is the practical concern rather than a design flaw. Test Composer resolution and transition behavior against your target framework version without using --ignore-platform-reqs. If constraints conflict, fork and vendor the package with an updated constraint instead of pinning your application backward.
- How do I define states and transitions on an Eloquent model?
- You define the allowed states and the valid transitions between them in one place on the model, alongside the trait that provides the stateful behavior. Keeping the definition centralized means the state diagram acts as a contract you can document and review. Calls to transition the model are then validated against that definition before any state change is applied. This is idiomatic Laravel with low ceremony and no new service to operate.
- Can the package prevent invalid state transitions?
- Yes. The package guards transitions by validating them against the declared state definitions, so an illegal move is rejected rather than silently applied. That guard logic lives with the model rather than leaking into your controllers. You should still add tests covering both valid and invalid transitions for each model you adopt. Handling the resulting domain errors explicitly in a service layer keeps HTTP concerns clean.
- How do I query models by their current state?
- The package exposes state query scopes, so you can filter Eloquent queries by state without writing raw where clauses. These scopes, together with the transition method, are the main public surface you should isolate if you want the package to stay swappable. Centralize their use in repositories or domain services instead of scattering them through controllers. That keeps a future migration to another state library limited to a small number of call sites.
- Does it fire Laravel events for transition side effects?
- Yes, the package hooks into Laravel events so you can attach side effects to state changes. That composes cleanly with existing listeners, observers, and policies you already use. Make those listeners idempotent and retry-safe, since side effects triggered by transitions may be replayed. Instrumenting transitions with logs and metrics before a wider rollout is worth doing.
- Does laravel-statable keep a history or audit trail of transitions?
- No, there is no built-in transition audit trail. If you need transition history for audit, compliance, or finance requirements, plan supplemental persistence alongside the package. A common approach is a dedicated transitions table or an event listener that records each change with actor, timestamp, and reason. Decide this before rollout, because retrofitting history is harder than adding it up front.
- Can it handle parallel states, sub-states, or conditional guards?
- No. This is a lightweight state machine, not a workflow engine: there are no parallel states, no hierarchical or nested sub-states, and no conditional guards beyond transition validation. It fits bounded domain models with linear or lightly branching lifecycles such as orders, subscriptions, invoices, and approvals. If your flows require orchestration, compensating actions, or sagas, you will outgrow the package and should evaluate a workflow engine instead.
- How does it compare to spatie/laravel-model-states or symfony/workflow?
- The API ergonomics here are simpler and the footprint is smaller, which makes it easy to read and easy to fork. The trade-off is maintenance posture: spatie/laravel-model-states is actively maintained and symfony/workflow offers far more capability for complex flows. If maintenance guarantees matter for your team, compare those options before committing. Otherwise adopt this one incrementally on a single bounded model and keep it behind an internal transition service.
- Is laravel-statable safe to use in production?
- The blast radius is contained: the dependency is thin, has a limited CVE surface, and is replaceable, so the risk is breakage on a future Laravel upgrade rather than failure in production. The real concern is lifecycle, with a single-maintainer signal, modest adoption around 96 stars, and a last release in July 2021. Treat it as internal code, fork or vendor it, and define who owns the fork and the upgrade-review cadence. Also consider whether concurrent transitions on the same record are possible in your app and add optimistic locking if they are.