State Machine Visualization Bundle Laravel Package

Product Decisions This Supports

• Documentation as a deliverable, not an afterthought. The package turns state machine configuration (order statuses, subscription lifecycle, payment flows, ticket workflows) into a visual diagram. That makes the canonical definition of a business process reviewable by people who don't read PHP — support leads, ops, compliance, designers.
• Workflow design review before build. When a roadmap item is "add a cancellation/refund/approval flow," a rendered state diagram is the cheapest artifact for a design review. It surfaces unreachable states, dead ends, missing transitions, and ambiguous ownership before engineering writes the handlers.
• Onboarding and support enablement. Support and QA can be pointed at a generated diagram instead of reverse-engineering transitions from code or stale Confluence pages. Reduces escalations of the "can a customer go from X to Y?" variety.
• Build vs. buy: buy (cheaply) or vendor. This is a dev-time tooling dependency, not a runtime one. At MIT license, near-zero integration cost, the calculus is "spend an afternoon wiring it into docs" vs. "keep hand-drawing diagrams that drift." Given zero dependents and a last release in 2022, the realistic decision is vendor/fork, don't depend — copy it into a tools/ directory or an internal fork so your documentation pipeline is not hostage to an unmaintained repo.
• Test coverage and QA planning. Enumerated states and transitions are a ready-made matrix for test cases; the diagram doubles as the coverage map for "which transitions have we never exercised?"
• Roadmap scoping input. When proposing new states (e.g., "add partially_refunded"), showing the before/after diagram in the spec makes the blast radius — new transitions, new guards, new notifications — concrete and easier to estimate and to reject.

When to Consider This Package

Consider it when all of the following hold:

• You are on Symfony, not Laravel, and you already use winzou/state-machine-bundle. This is a Symfony bundle; despite the "Laravel/PHP" framing, there is no Laravel service provider or config here, and composer require in a Laravel app gets you nothing usable.
• You already have a Graphviz/dot toolchain available in the environment where diagrams are generated (the bundle is a thin visualization layer, not a renderer).
• Your need is static documentation generation — a diagram in a README, a CI artifact, or a design doc — rather than a runtime API for querying the machine.
• You accept the maintenance profile: 12 stars, 0 dependents, last release November 2022, no evidence of active upkeep. Treat it as a snapshot of an idea, not a maintained dependency. Pin it, vendor it, or fork it, and own the ~200 lines yourself.

Look elsewhere — or don't bother — when:

• You're on Laravel. Look at spatie/laravel-model-states plus a custom exporter, or generate Mermaid/PlantUML from your own transition config. Mermaid diagrams in Markdown are the higher-leverage 2026 answer: no Graphviz binary, renders on GitHub/GitLab natively.
• You're on modern Symfony Workflow (symfony/workflow) rather than the legacy winzou bundle. Workflow ships GraphvizDumper and a workflow:dump --dump-format=dot command out of the box. This package adds nothing there, and the "buy vs. build" question is settled by the framework.
• You need active maintenance, security patching, or vendor support. Zero dependents is a strong signal: nobody is watching this repo. That's fine for a docs script, disqualifying for anything on a critical path.
• You need runtime introspection (admin UI showing current state, available transitions). This is build-time tooling; use the state machine's own API for that.
• Your team won't maintain the diagram pipeline. A visualization that isn't regenerated in CI rots exactly as fast as the hand-drawn version it replaced. No automation commitment, no value.

How to Pitch It (Stakeholders)

To executives: This is a small, free, open-source tool that automatically draws our business workflows — order statuses, subscription states, approval chains — directly from the code that enforces them. The value is alignment and risk reduction, not new functionality: it makes hidden process logic visible to the business, catches design gaps before they ship, and shortens onboarding for support and QA. Cost is an afternoon of an engineer's time and effectively zero licensing. The caveat is honest: the project is small and unmaintained, so we treat it as a starting point we own a copy of, not a long-term vendor dependency. Recommend a time-boxed pilot on one workflow, with a go/no-go on whether the diagrams actually get used.

To engineering: It's a thin Symfony bundle on top of winzou/state-machine-bundle that dumps your configured states and transitions to a rendered graph. Low risk, but do not require it as a live dependency — 12 stars, zero dependents, last touched 2022. Vendor or fork it, wire it into a make docs target or CI step so the diagram regenerates on every config change, and commit the output. If we're on symfony/workflow instead, don't adopt this at all — use the built-in workflow:dump and save ourselves the fork. Either way, prefer emitting Mermaid so the diagram renders in the repo without a local Graphviz install.

To the team deciding: The package itself is marginal — the practice is not. Static diagrams generated from the single source of truth are worth having regardless of which tool emits them. Frame the decision as "adopt the practice, pick the cheapest emitter," and this package is one option among several, best suited to a Symfony shop already on winzou.