Product Decisions This Supports
- Exposing lifecycle state over the API. Whether a domain object's lifecycle (order fulfillment, KYC review, editorial approval, subscription dunning, ticket triage) should be modeled as an explicit state machine and surfaced as first-class API operations rather than a free-form
status string that any client can PATCH.
- Build vs. buy vs. fork. This package is a thin integration layer between API Platform and Symfony Workflow. It answers the question "is workflow-aware resource handling commodity glue we adopt, or 150 lines we own?" — the answer here leans hard toward own it, given the archive status.
- Roadmap: platform capability vs. per-domain feature. Do we invest in one shared "workflow transitions as API operations" capability (consistent auth, guards, audit, error semantics across teams), or let each domain hand-roll transition endpoints? This package is a useful reference for what the shared capability looks like at minimum.
- Consistency of transition semantics. A pattern like this forces a decision on how transitions are addressed (
/orders/{id}/transition/{name} vs. PATCH with a state field), what HTTP status/error shape a blocked transition returns, and whether guards map to 409/422. Those are API-contract decisions a PM should own once, not per squad.
- Audit and compliance posture. State machines on regulated flows (payments, onboarding, claims) need a transition log and permission model. Evaluating this package surfaces the gap: the integration layer maps transitions; it does not give you the audit trail or guard enforcement story for free.
- Use cases worth scoping: internal back-office tooling and admin consoles (highest fit — low blast radius, high churn), B2B approval flows, content pipelines, and any API where clients should be able to request a transition but not set arbitrary state.
When to Consider This Package
Consider it as a reference or internal fork only when:
- You are on a legacy-compatible stack — API Platform 2.x with Symfony 4/5-era conventions — and need transition endpoints in days, not weeks.
- You want a concrete, working illustration of how Symfony Workflow definitions map onto API Platform operations before writing your own state processor.
- You accept a fork: the repository is archived, meaning no security patches, no compatibility work for API Platform 3, and no upstream response to issues. Anything you adopt becomes your maintenance burden on day one.
- Your team is small enough that vendoring ~a few hundred lines into the codebase is cheaper than a dependency review and an ongoing "is it still maintained?" ritual.
Look elsewhere — or build in-house — when:
- You are on API Platform 3. The idiomatic path is a custom state processor/provider pair, which is small, testable, and yours to evolve. This is the default recommendation.
- You need audit logging, per-transition authorization, idempotency keys, optimistic concurrency, or rollback semantics. Those are product requirements, not glue, and belong in your own layer.
- You need vendor support, an SLA, or a security response channel. Eleven stars and an archive flag mean zero of that.
- You want transition discovery (clients learning valid transitions from the API) — that is a design exercise worth doing deliberately, not inheriting.
- You simply need CRUD with a constrained enum. A validator plus a permission check beats a workflow engine.
How to Pitch It (Stakeholders)
To executives (one paragraph): This is a small open-source adapter that lets the Symfony workflow engine drive API endpoints, so state changes like "approve," "ship," or "publish" become explicit, permissioned actions instead of clients writing arbitrary status values. It is archived and unmaintained — we would not take it as a runtime dependency. Its value to us is as a reference design: it shows the shape of a capability we should own, and reading it costs a day while reimplementing the equivalent on our current framework costs roughly one sprint. Recommendation: treat it as design input, fund the small in-house build, and avoid the supply-chain and maintenance risk.
To engineering: The pattern is the deliverable, not the code. It demonstrates mapping workflow transitions onto API operations and — importantly — where the seams are: guard failures need a defined HTTP contract, transitions need authorization, and state changes need an audit record. Our equivalent should be a thin state processor/provider pair on API Platform 3, with the workflow definition as the single source of truth and a transition log emitted alongside. Budget one engineer, one sprint, plus tests; you get ownership, API Platform 3 compatibility, and no archived dependency.
Framing the risk explicitly: low stars, archived status, no maintainer, no security channel, no upgrade path. Any proposal that puts this in production must answer "who patches it in eighteen months?" If the answer is a name, the decision is actually fork and own it — in which case say so and staff it.