Laravel Interlock Laravel Package

Product Decisions This Supports

• Model the lifecycle formally vs. keep a status string column. This package makes the "state machine as first-class domain object" option cheap to trial: transitions are classes, states are declared, and illegal writes are rejected at the Eloquent layer rather than in scattered controllers and observers. That reframes "should we just add another status value?" from a one-line PR into a modeled decision — which is usually the decision you want to be deliberate about.
• Build vs. buy vs. adopt for workflow logic. The alternative is hand-rolled status columns plus ad-hoc guards, or a heavier workflow engine (Temporal, Camunda). Interlock sits in the middle: it buys enforcement, history, guards, authorization, and triggers without a new runtime. For a Laravel monolith this is often the cheapest credible option.
• Where the source of truth for state lives. Because direct writes, mass assignment, and builder-level updates are rejected, state can only move through named transitions. That's a product-level decision about whether state is authoritative (an invariant the app trusts) or descriptive (a label someone remembered to update).
• Auditability and compliance posture. Opt-in history records transitions and bypassed writes, with shared history tables across integer/UUID/ULID keys. This supports decisions like "can we answer 'who moved this claim to Approved, and when?' without a log-diving exercise?" — relevant for orders, payments, KYC, claims, subscriptions, ticketing, approvals.
• Concurrency and double-submit behavior. Compare-and-swap transitions with explicit stale-state exceptions turn "two support agents clicked Approve" into a product decision with a defined answer, rather than an emergent bug class.
• Human-driven vs. automated transitions. Triggers let transitions fire themselves once a condition holds, with system-only transitions behind a scope and authorization deliberately skipped for triggered runs. This supports deciding which steps need a human approval gate and which are just waiting on time or an external signal.
• SLA and stuck-workflow visibility. Time-in-state recording, trigger status reporting, overdue-trigger failure, and trigger caps/chunked fan-out make "how long do orders sit in Awaiting Stock?" a queryable product metric instead of an analytics afterthought.
• API/UI contract decisions. XState JSON/TypeScript export, Mermaid diagrams, and Stately Sketch visualization mean the backend machine definition can be shared with frontend teams or docs. That affects whether the client can render allowed actions reliably (transitions available to this actor right now helps here).
• Scoping of "escape hatches." The explicit bypass for factories and opted-in tests, plus replicate resetting state, is a decision about how much friction developers accept in exchange for integrity — and where that friction becomes counterproductive.

When to Consider This Package

Consider it when:

• You have an Eloquent model with a status/state column that already has rules around it, and those rules are enforced (or not) inconsistently across controllers, jobs, Filament/Nova resources, and seeders.
• Multiple actors write the same state field — customer, support agent, system jobs — and authorization needs to differ per transition.
• The domain has genuine concurrency risk: payments, fulfillment, approvals, onboarding, ticketing, subscriptions.
• You need an audit trail for state changes, including deliberate overrides, and don't want to build a bespoke audit table per model.
• You want to automate time-based or condition-based advances (auto-close, retry, escalate) with queue routing, caps, and overdue alerting.
• You want the state machine visible to non-engineers or the frontend (Mermaid, XState, Sketch export) and testable in isolation (fakes plus transition assertions).
• You are on Laravel and comfortable with class-per-transition as a structural convention.

Look elsewhere when:

• The "state" is genuinely trivial — a boolean, a soft-delete flag, a draft/published toggle with no rules. Enforcement overhead buys nothing.
• The workflow spans multiple services and needs distributed orchestration, compensation, and long-running durable execution. This is a per-model, in-app tool; a dedicated engine (Temporal et al.) is the right call.
• Your domain logic isn't in Eloquent, or you're polyglot with the workflow center of gravity outside PHP. The XState export helps with visualization but doesn't move the source of truth.
• You need a mature, stable API today. This is v0.1.0, the entire public surface landed in a single initial release, and pre-1.0 packages should be expected to churn. Adopt behind a single pilot domain, not across the whole codebase.
• Throughput on guarded models is extreme and every write path must be minimal — every enforced write now passes through transition/guard/authorization checks.
• Your team won't accept the structural cost. Class-per-transition, machine declarations per model, and an enforced bypass discipline are real conventions; if they'll be fought, you'll end up with bypassed writes everywhere and get the worst of both.
• You already have an entrenched state machine implementation — migrating is a nontrivial refactor with no incremental path described.

How to Pitch It (Stakeholders)

To executives: Workflow state is currently enforced by convention — nothing stops code, a console command, or a well-meaning support action from writing an invalid status. This package makes illegal state changes structurally impossible, records who changed what and when (including deliberate overrides), and gives us a readable map of every lifecycle in the product. The business outcomes are fewer "order stuck in limbo" incidents, a defensible audit trail for compliance conversations, faster onboarding because the workflow is documented as code and diagram, and the option to automate time-based steps instead of paying people to chase them. It is open source, adds no new infrastructure, and can be piloted on one model before any wider commitment.

To engineering: It's a Laravel package that turns a status column into an enforced state machine. Direct writes, mass assignment, and builder updates to guarded attributes are rejected; state only moves through named transition classes, each with its own guard and authorization check. You get compare-and-swap transitions with explicit stale-state handling, system-only transitions behind a scope, queue-backed triggers with caps and overdue detection, opt-in history, time-in-state, nested states, multiple machines per model, query scopes, and soundness checks for unreachable/final states. Tests get fakes and transition assertions; factories and opted-in tests get a sanctioned bypass. Machines export to Mermaid and XState so the frontend and docs stay in sync. Caveat: it's v0.1.0 — treat the API as unstable, pilot on one domain, and keep the bypass surface small and reviewed.

To the pilot team / skeptics: The trade is friction for integrity. You will write more classes and you will occasionally be annoyed that a seeder can't just set status. In exchange, "how did this record get here" becomes answerable, double-submits become a handled case rather than a mystery, and the workflow becomes something a new hire can read. Start with the model whose status field causes the most support tickets.