Weave Code
Laravel Enum States Laravel Package
innoge/laravel-enum-states
A state machine for Eloquent built on native PHP enums. Define transitions, defaults, and lifecycle actions on the enum itself, register fields with a single attribute, and keep your normal model casts. Invalid transitions throw; defaults apply automatically.
A state machine for Eloquent, built on native PHP enums. No state classes, no model trait, no extra tables.
Frequently asked questions about Laravel Enum States
- How do I install innoge/laravel-enum-states in a Laravel app?
- Install it with Composer using composer require innoge/laravel-enum-states. You need PHP 8.1 or newer for native enums and attributes. Cast an existing string or integer column to your enum, add the StateMachine attribute to the model field, and implement configureStateMachine on the enum. No database migration is required if the underlying column already exists.
- Which Laravel and PHP versions does laravel-enum-states support?
- The package depends on native PHP enums and attributes, so PHP 8.1 or newer is required. It also needs a modern Laravel and Eloquent version, but the exact Laravel constraints should be checked in the package composer.json before you plan adoption. Small packages can lag behind new Laravel major releases, so verify support for your target version in a quick spike.
- How are state transitions enforced, and can model update() or mass assignment bypass them?
- The README says transitions are validated on save and invalid transitions throw, and that the default is applied when the field is null. The overview does not document whether the guard hooks Eloquent saving and updating events or only runs when an explicit transition method is called. Test direct assignment and mass assignment in a spike, because a guard that only applies to a dedicated transition call can be bypassed by setting the status and saving normally.
- Can one Eloquent model have multiple state machine fields?
- Yes, the design registers fields with a single attribute, so you can apply it to more than one enum-backed column on the same model. What is less clear from the overview is whether transitions on field A and field B interact in any way. Add a test for models that update two state fields in the same request to confirm the behavior you need.
- What exception is thrown for an invalid transition, and can I return a 422 from an API?
- Invalid transitions throw according to the package overview, which is the right behavior for API and queue workflows. Confirm the exact exception class is typed and catchable so you can map it to a 422 response in your HTTP layer and to a dead-letter or retry path in queued jobs. Avoid catching generic exceptions around every transition, because that hides real application errors.
- How do enter, leave, and transition actions work, and do they run inside the database transaction?
- Actions can be invokable classes or closures attached to enter, leave, or a specific transition, and they are resolved through the Laravel container. That gives you dependency injection for mail, jobs, and service calls without putting side effects in controllers. The overview does not state whether actions run inside the same database transaction as the state change, so use after-commit dispatch for external side effects if atomicity matters.
- Does laravel-enum-states support int-backed enums, enum casts, and where('status', Status::Active) queries?
- The package is built on native PHP enums and keeps your normal Eloquent enum casts, so standard Laravel enum query building should continue to work. Int-backed enums are likely supported because they are native enum cases, but verify that explicitly if your schema uses integer status columns. Also test scopes and where clauses against the enum cast before relying on them in production filters.
- How does laravel-enum-states compare with spatie/laravel-model-states?
- Spatie's package uses state classes, a model trait, and custom casts, which gives each state a natural home for labels, colors, allowed actors, and per-state behavior. Laravel Enum States keeps states as plain enum cases and puts the graph on the enum itself, so there are fewer new concepts and no extra model trait. The trade-off is that per-state business rules tend to leak into Blade, API resources, Filament, or match statements when the domain has rich state-specific behavior.
- Is there transition history or audit logging built in?
- No. The no-extra-tables design is a deliberate feature and also a ceiling, so there is no append-only transition log or event-sourcing store included. If you need audit history, record transitions through model events, an observer, or a dedicated audit package. Decide this before launch, because retrofitting history after production data exists is harder.
- Is innoge/laravel-enum-states actively maintained and safe for production?
- The main risk is vendor risk rather than technology risk: the repository has a small maintainer footprint, few dependents, and no strong ecosystem signal. Pin the version in composer.json, run the package tests in your own suite, and check recent commits and Laravel compatibility before committing. For critical workflows, wrap transitions behind your own application service so you can replace the package later without rewriting every model.
Weaver
How can I help you explore Laravel packages today?