State Machine Abstraction Laravel Package

Technical Evaluation

Architecture fit. sylius/state-machine-abstraction is an interface-only package: it ships the contracts (StateMachineInterface, StateMachineFactoryInterface, TransitionInterface) plus exceptions and a couple of callback interfaces. It carries no engine. The concrete engine lives in sylius/state-machine (a thin wrapper over symfony/workflow), and the whole stack sits inside Sylius's DDD/Symfony idiom (factory + service registry, no Eloquent). For a Laravel codebase the fit is therefore indirect: the abstraction exists so Sylius could swap engines (Winzou → Symfony Workflow) without touching every bundle. That value proposition only pays off if we realistically expect to swap state-machine engines — otherwise we are paying for an indirection we will never exercise.

Integration feasibility. Composer-installable and MIT-licensed, but it is a Git-subtree split of the sylius/sylius monorepo, not a standalone project with its own release cadence. Wiring it into Laravel means writing a service provider that binds StateMachineFactoryInterface and the underlying ServiceRegistryInterface, plus supplying graph definitions in Symfony Workflow's YAML/XML/PHP-array format. There is no Laravel bridge package, no docs target, and no tests aimed at non-Symfony hosts — the "0 dependents / 0 stars" is misleading (real usage is inside Sylius bundles) but it also confirms there is no independent community.

Technical risk. Three concerns. First, concentration risk: the package's fate is tied to the Sylius 2.x release train, with no independent semver, LTS, or security process. Second, namespace lock-in to Sylius\Component\StateMachine\…, which reads oddly in a Laravel app and complicates static analysis and upgrade tooling. Third, the abstraction is thin enough that migration cost off it is low (good), but the real dependency is symfony/workflow, whose mental model (places, transitions, marking store, guards, metadata) is non-trivial and not Laravel-idiomatic.

Key questions.

1. Do we have a credible scenario in which we change state-machine engines in the next 24 months? If no, skip the abstraction and use the engine directly.
2. Are we integrating with Sylius, or building standalone in Laravel? If the latter, why take a Symfony-namespaced dependency at all?
3. Who owns Symfony Workflow semantics on the team, and do we accept a framework-agnostic engine over a Laravel-native one (spatie/laravel-model-states)?
4. What is the persistence story — single column, property path, or JSON? That decision is not made by this package.
5. Do we need Sylius compatibility guarantees (version alignment, deprecation policy) as a formal requirement?

Integration Approach

Stack fit. Symfony-first. In Laravel, the pragmatic composition is sylius/state-machine-abstraction + sylius/state-machine + symfony/workflow, bound through a small service provider. The abstraction itself is only a few interfaces and exceptions, so the integration surface is small; the effort sits in the engine wiring, graph authoring, and Eloquent persistence — none of which this package solves. The Laravel-native alternative (spatie/laravel-model-states) is more idiomatic but less portable and lacks Symfony Workflow's guard/metadata richness.

Migration path. There are three honest routes:

• Adapter-over-existing: implement StateMachineInterface over whatever we already do (enum + service, or Winzou), then swap engines later behind the abstraction. Lowest commitment; only useful if a swap is planned.
• Direct engine: adopt symfony/workflow alone and skip the abstraction. Recommended for standalone Laravel unless portability is a stated requirement.
• Full Sylius stack: adopt the abstraction + engine because we are building alongside Sylius or an ecosystem that already speaks these contracts. This is the only case where the package is the natural choice.

Compatibility. Baseline is Sylius 2.x (PHP 8.1+/8.2+, Symfony 6.4/7.x). Laravel 10/11 ship compatible Symfony 7 components; Laravel 9 is a question mark and should be checked against the resolved constraint matrix before committing. No official Laravel support matrix exists, so pin versions explicitly and treat upgrades as planned work.

Sequencing.

1. Spike (1–2 days): bind the factory in a service provider and drive one workflow against a dummy Eloquent model; confirm Symfony Workflow graph parsing, marking store, and event dispatch behave under Laravel's container.
2. Graph design: author workflow definitions (PHP arrays preferred over YAML for testability and IDE support), including guards and metadata.
3. Persistence: choose single-column vs property-path marking; add optimistic locking or row-level guards if concurrency matters.
4. Error mapping: translate TransitionFailedException into Laravel-idiomatic responses via the exception handler.
5. Tests: unit-test transitions against the abstraction, and add a contract test that would survive an engine swap (this is the abstraction's only real payoff).
6. Decision gate: if the swap scenario has evaporated by step 5, collapse to symfony/workflow directly.

Operational Impact

Maintenance. Effectively maintained as part of the Sylius monorepo; the interfaces are stable and churn is low, but upgrades arrive with Sylius releases rather than independent tags, and there is no changelog, deprecation policy, or security advisory stream for the split package itself. Expect a version-alignment check on every Sylius major.

Support. Support channel is Sylius GitHub and Slack; there is no Laravel-community answer to "why did my transition fail." The team owning this needs internal competence in Symfony Workflow semantics — guards, marking store, event listeners — not just Laravel familiarity.

Scaling. State machines are per-entity and horizontally scale cleanly; the hot path is workflow graph parsing, which should be cached (compiled metadata) rather than rebuilt per request. The service-registry pattern is a service locator — cheap at runtime but a testing and observability tax; prefer constructor injection around it. Watch registry lookups in hot loops.

Failure modes.

• Guard rejection surfaces as TransitionFailedException — must be mapped to clean domain errors and user-facing messages, otherwise it leaks as 500s.
• Graph misconfiguration is a runtime failure, not a compile-time one; mitigate with a boot-time validation pass and contract tests.
• Version drift at Sylius majors can break contracts (the v1→v2 boundary is precedent); pin and schedule upgrades.
• Silent abstraction bypass — developers calling the engine directly undermines the portability guarantee; enforce via architecture tests (e.g., PHP arkitect or deptrac).
• Persistence edge cases — concurrent transitions, partial failure across multiple aggregates; the abstraction provides no saga/compensation primitives.

Ramp-up. The abstraction itself is roughly an hour to read. Symfony Workflow concepts take one to two days for a Laravel-native developer, and a production-grade integration (persistence, guards, events, testing, error handling) is realistically three to five days for one competent engineer. Expect cultural friction: a Laravel-first team will push for spatie/laravel-model-states, and the counter-argument must be a concrete portability requirement, not theoretical purity.