Laravel Statable Laravel Package

Technical Evaluation

Architecture fit The package attaches stateful behavior to any Eloquent model via a trait, defines allowed states and transitions in one place, guards invalid transitions, exposes state query scopes, and hooks Laravel events for side effects. This is idiomatic Laravel: low ceremony, no external engine, no new infrastructure. It fits bounded domain models with clear lifecycle semantics — orders, subscriptions, invoices, approvals, onboarding flows — where transitions are linear or lightly branching. It is not a workflow engine: no parallel states, no hierarchical/sub-states, no temporal or conditional guards beyond transition validation, and no built-in transition audit trail. Teams expecting orchestration (compensating actions, sagas, long-running workflows) will outgrow it.

Integration feasibility High. The surface area is one trait plus configuration, installable through Composer under a permissive MIT license. The trait-based pattern composes cleanly with existing Laravel events, policies, and observers. Vendoring or forking is realistic because the code footprint is small.

Technical risk The dominant risk is lifecycle, not design. Last release was 2021-07-15, adoption is modest (96 stars), and there is a single-maintainer signal. There is no evidence of a security policy, active issue triage, or stated support for Laravel 10/11. A pure state machine has a limited CVE surface, but Eloquent internals evolve across majors, so compatibility is the practical concern. Blast radius is contained: the dependency is thin and replaceable, so the risk is "will it break on the next Laravel upgrade" rather than "will it fail in production."

Key questions

• Which Laravel and PHP versions does the target project pin, and does the package resolve against them?
• Is transition history required for audit, compliance, or finance? (If yes, plan supplemental persistence.)
• Do flows need parallel states, sub-states, or conditional guards beyond transition validity?
• Who owns the fork if upstream stays dormant, and what is the upgrade-review cadence?
• How will transition side effects (events) be made idempotent and retry-safe?
• Are concurrent transitions on the same record possible, and is optimistic locking needed?

Integration Approach

Stack fit Any Laravel application on Eloquent. It aligns with teams already using Laravel events for side effects and with domain models that have an explicit lifecycle. Where maintenance guarantees matter, compare against spatie/laravel-model-states or symfony/workflow before committing; the API ergonomics here are simpler, but the maintenance posture is weaker.

Migration path Adopt incrementally on one bounded model, and wrap the trait behind a thin internal transition service or repository so the package is a swappable implementation detail. Centralize transition calls in domain services rather than controllers so guard logic does not leak into HTTP layers. The seam for a future migration is the transition method plus state query scopes — keep those two surfaces isolated and the package becomes replaceable without touching call sites.

Compatibility Run a spike against the exact target PHP/Laravel combination in a sandbox before any commitment. Confirm Composer constraints resolve without --ignore-platform-reqs. If constraints conflict with a current framework version, fork and vendor with an updated constraint rather than pinning the app backward.

Sequencing

1. Spike the package on one non-critical model in a feature branch.
2. Validate compatibility, confirm event hooks fire as expected, and add test coverage for valid and invalid transitions.
3. Define states and transitions in one place; document the state diagram as a contract.
4. Wrap transitions in a domain service with explicit domain-error handling.
5. Instrument transitions (logs, metrics) before wider rollout.
6. Roll out model by model; review at each step.

Operational Impact

Maintenance Treat the package as internal code. Fork or vendor it, pin the version, and assign a named owner. Expect low churn given the small scope, but budget a compatibility review at every Laravel major upgrade. The real maintenance cost is not bug fixes — it is periodic framework-compatibility validation.

Support Community support is thin at this adoption level, and there is no vendor SLA. Rely on internal Laravel expertise, keep an internal README covering semantics, and document the transition contract per model so knowledge does not concentrate in one engineer.

Scaling Runtime overhead is negligible — the state machine adds no infrastructure and is stateless across requests. The practical scaling concern is database: ensure the state column is indexed and that state-scoped queries do not introduce N+1 patterns in list views. No horizontal scaling or caching implications.

Failure modes

• Invalid transition throws — must be caught and mapped to a domain error, never surfaced as a 500.
• Event side effects failing after state commit — use transactional outbox or retry semantics so a state change and its downstream effects do not silently diverge.
• Bypassed transitions — direct state column updates outside the trait defeat the guarantee; guard at the repository or database level.
• Concurrent transitions — two requests on the same record can race without optimistic locking.
• Framework upgrade breakage — the highest-probability incident; mitigate with version pinning and pre-upgrade test runs.

Ramp-up Low. A Laravel developer is productive in one to two days: the trait, the states/transitions definition, and the transition API are self-evident. Allow roughly half a day to internalize the semantics and edge cases. Because upstream documentation is thin, an internal onboarding note covering the state diagram, error handling, and event side effects is essential and should be written before broad adoption.