Laravel States Laravel Package

Technical Evaluation

Architecture fit: aw-studio/laravel-states is a state-machine package that attaches typed state objects to Eloquent models via a states() relation and per-type accessors ($model->{type}). It fits codebases already committed to Eloquent-domain modelling where state transitions carry guards, side effects, and audit requirements. It is not a workflow/BPM engine — if the roadmap includes multi-actor approval chains, parallel branches, or long-running sagas, this package is a component, not a solution.

Integration feasibility: High. Composer-installable, no external services, no schema beyond the package's own state storage, and the transition API is a small surface (transition(), guards, canTransitionTo-style checks). A single developer can wire a pilot model in under a day. The main effort is not the package but the surrounding discipline: deciding which models get state machines, where transition side effects live, and how state is exposed through the API layer.

Technical risk: Low-to-moderate. v2.0.1 is a patch release that removes States::transition() from the $model->states() relation. Critically, that method called a nonexistent method and therefore always threw — it was never functional. Removal is API hygiene, not a behavioural regression: no working code path can break. The residual risk is cosmetic — code or documentation that references the removed call will now fail with a different exception class at the same point it previously failed. Actual risk concentrates in the v2.0.0 baseline (a recent major), not this patch.

Key questions:

• Which models are state-machine candidates, and is there an audit/timeline requirement the package must satisfy natively versus via observers?
• Do any call sites use $model->states()->transition(...) — including tests, seeders, factories, queued jobs, and dead/commented branches? Those must migrate to $model->{type}->transition().
• Is the team pinned to ^2.0.0, and does the dependency policy allow patch-level auto-updates?
• Who owns the state vocabulary and guard logic — product or engineering — and where is it documented?
• Are transition side effects (notifications, webhooks, ledger writes) intended to run inside or outside the DB transaction?

Integration Approach

Stack fit: Native Laravel/PHP. Requires a Laravel version consistent with the v2.x support matrix — confirm against the project's composer.json before committing. No queue, cache, or infrastructure dependency is introduced, so it slots into existing CI without new services.

Migration path: Adopt at ^2.0.1 directly; do not start on 2.0.0 and patch later, since the fixed surface is the one you want to write against. For the removed method: run a repository-wide search for states()->transition (including ->states()->transition across multiple lines, and string references in docs). Each hit becomes a one-line rewrite to $model->{type}->transition(). If any hit is in a path covered only by integration tests, add a targeted test before rewriting — those are the ones most likely to be silently dead.

Compatibility: v2.0.1 is drop-in from v2.0.0 for all functioning code. Anything still calling the removed method was already broken at runtime, so treat those as pre-existing defects surfaced by the upgrade, not as upgrade regressions. Pin ^2.0.1 in composer.json and commit the lockfile.

Sequencing:

1. Confirm Laravel/PHP version support and add the dependency at ^2.0.1.
2. Grep-and-rewrite the removed method across app, tests, seeders, and docs.
3. Pilot on one low-traffic model with a single state type; instrument transitions.
4. Introduce guards and transition side effects on the pilot; validate with the product owner.
5. Roll out to remaining models one at a time, each behind its own PR and state-vocabulary review.

Operational Impact

Maintenance: Light. The package is a single-maintainer open-source project (aw-studio), so bus factor is a genuine consideration — budget for the possibility of forking or vendoring. State definitions live in application code, so the blast radius of an upstream change is bounded to the package API surface, which is small.

Support: No vendor SLA; support is GitHub issues. Escalation path should be "pin, fork, or replace" rather than "raise a ticket." Nominate an internal owner for the state vocabulary — without one, state sets drift and guards become inconsistent across models.

Scaling: Negligible runtime overhead — transitions are in-process method calls plus the existing Eloquent write. The scaling constraint is not throughput but state-space growth: as models gain state types, the transition graph and guard matrix become the maintainability bottleneck. Enforce a documented state diagram per model before merging new states.

Failure modes:

• Calling the removed method — throws immediately. Detectable in CI; mitigate with the grep step and a lint pass in the upgrade PR.
• Guard-less transitions — invalid state changes succeed silently. Mitigate by requiring guards on every transition and testing negative cases.
• Side effects inside vs. outside the transaction — notifications fired mid-transaction can emit on rollback. Decide and document the convention.
• Upstream major bump — v2 was recent; a v3 would likely carry real breaking changes. Pin to ^2.0.1 and review changelogs before any minor bump.
• Single-maintainer abandonment — monitor release cadence; flag if the repo goes quiet for two quarters.

Ramp-up: Low. A Laravel-proficient engineer is productive in half a day; the conceptual load is state-machine modelling, not the API. Invest the onboarding time in the domain state diagrams rather than in package mechanics — that is where defects will originate. Produce a short internal runbook covering: adding a state, adding a guard, migrating the removed method, and where transition side effects belong.