- How do I install juststeveking/state-machine in a Laravel application?
- Install it as a standard Composer dependency with composer require juststeveking/state-machine. If the package ships a service provider, Laravel package discovery registers it automatically; confirm this in the repository's composer.json during your spike. There are no external services to provision and no new runtime such as Redis or a queue worker, so the operational footprint stays flat. The only likely schema change is the state column itself, which should be verified against the migration stubs.
- Which PHP and Laravel versions does juststeveking/state-machine support?
- The published release notes point to a changelog only, so the support matrix is not confirmed from the description alone. Read composer.json for the php and illuminate/support constraints and check them against both your current and next-upgrade Laravel targets. The 1.0.0 milestone indicates a semver commitment, which makes version constraints more predictable than a 0.x package. Confirm this before the technical spike closes.
- How do I define states and allowed transitions with this state machine?
- The package is built around a declarative transition map: the set of states an object can occupy plus the from-to pairs that are legal. The machine validates each requested transition against that map and rejects anything not explicitly allowed, which replaces scattered status writes and boolean checks with a single testable definition. Because it is framework-agnostic, the same map can be applied to an Eloquent model or a plain PHP object. The exact API shape and class names should be verified against the repository README.
- Can I use juststeveking/state-machine with Eloquent models?
- Yes in practice, because the package is framework-agnostic and is expected to attach to an Eloquent model through a trait or base class, leaving the model responsible only for persistence. That aligns with Laravel's container, model events, and policy and Gate layers, so authorization and side effects can stay outside the transition map. For purely event-sourced designs or teams already running Symfony Workflow or Temporal, the package duplicates an existing capability rather than filling a gap.
- How does the package store the current state — a status column or a separate table?
- Persistence is expected to be column-based on the model's own table, possibly with an index, rather than requiring an auxiliary table. Whether the machine writes the new state itself or returns it for you to persist is a detail that must be confirmed from the source. This is one of the fastest questions to answer in the spike and it determines how invasive the migration path is. Keep your existing column name and values stable so legacy accessors can delegate to the machine.
- Can I add guard conditions or authorization checks before a transition runs?
- Declarative guard conditions are the expected mechanism, letting a transition succeed only when domain rules hold. Whether there is a first-class hook into Laravel policies or Gates is not confirmed, so verify that during the spike if authorization must gate transitions. A recommended convention is to keep guards in policies and side effects in listeners, so the transition map does not accrete notification and business logic until it becomes a god-object. That is an adoption risk rather than a defect in the package.
- Is this state machine safe for concurrent requests and race conditions?
- State machines are read-modify-write by nature, so two concurrent requests can both validate a transition and both write it if nothing prevents it. Transactional transitions or row-level locking support is not confirmed from the available material and is the single largest production risk to resolve before adoption. If the package does not provide it, wrap transitions in a database transaction with a locking read on the model row. Test this explicitly in your CI with a concurrent request simulation.
- Does the package fire events I can use for audit logging and downstream side effects?
- An event or observer surface for audit logging is expected but not confirmed, so check the source for dispatched transition events. If none exist, Eloquent model events updated and saved can serve as a fallback, though they capture column changes rather than intent. A sensible migration sequence is to backfill an audit trail from whatever events are available before enabling strict guards in production. Keep side effects in listeners so the transition map stays declarative.
- Does juststeveking/state-machine include test helpers for asserting transitions?
- Test helpers for asserting allowed and denied transitions are not confirmed, so verify whether the package ships assertions suitable for your CI pipeline. If it does not, feature tests can call the transition method, assert the resulting state, and assert an exception or unchanged state for illegal transitions. Either way, the declarative map makes the full set of legal transitions cheap to enumerate in a data provider. That testability is a large part of the package's value compared with free-text status updates.
- How does it compare to Symfony Workflow or Temporal, and what are the maintenance risks?
- This package targets plain Laravel and PHP applications that need a governed lifecycle without adding a workflow engine or new runtime infrastructure, which is its principal advantage over Symfony Workflow or Temporal. Choose those alternatives if you need event-sourced orchestration, long-running sagas, or durable execution. The trade-off is a single-maintainer package: the 1.0.0 tag commits to semver but not to resourcing, so pin the version, review release cadence over the last twelve months, and check the license and security disclosure policy before adoption.