madmind/state-machine-visualization-bundle
Visualize state machines and workflows in your Symfony app with clear, auto-generated diagrams of states, transitions, and places. This bundle makes it easy to debug, document, and explain workflow logic, helping your team understand complex state transitions at a glance.
Before anything else: this is a Symfony bundle, not a Laravel package. It is a visualization add-on for winzou/state-machine-bundle, which itself wraps the winzou/state-machine (SM) library. You cannot composer require it into a Laravel app and expect it to boot — there is no service provider, no config/ merge, and the routes are registered through Symfony's bundle kernel. Treat it as a reference implementation you read, and a working tool you install only in a Symfony application.
If you are in a Symfony app that already uses winzou/state-machine-bundle:
composer require madmind/state-machine-visualization-bundle (verify PHP/Symfony constraints first — last tagged release is Nov 2022, so expect Symfony 5.x/6.x and PHP 8.x).config/bundles.php:
return [
MadMind\StateMachineVisualizationBundle\StateMachineVisualizationBundle::class => ['dev' => true, 'test' => true],
];
winzou_state_machine in config/packages/. The bundle introspects that config; with no machines defined the visualization surface is empty.php bin/console debug:router | grep -i state to get the exact path — route naming has shifted between versions). You should get a rendered graph (SVG/PNG) or raw DOT output for each configured machine.First use case: a new developer joins the team and needs to understand the Order lifecycle. Instead of reading a 300-line YAML block, they open the visualization URL and see the states and transitions. That is the entire value proposition — it converts config into a picture.
For Laravel developers evaluating this: the correct analog is Laravel's symfony/workflow integration or a hand-rolled state machine (e.g., spatie/laravel-model-states). There is no drop-in Laravel port of this bundle. Your realistic path is to (a) read this bundle's source to learn how it walks the config, and (b) generate the DOT graph yourself using graphp/graphviz or by shelling out to dot. A ~40-line Artisan command that reads your state machine config and emits DOT is roughly equivalent to what this bundle does.
Read the config, render the graph. The bundle's job is introspection: it reads winzou_state-machine configuration (states, transitions, callbacks) and emits a Graphviz DOT document. Everything else is presentation. If you need to customize output, the pattern is to mirror this — build a DOT string from your source of truth, then hand it to Graphviz.
Use it in dev/test only. Register the bundle under ['dev' => true, 'test' => true] as above. In production this is a free attack surface: it exposes your domain's internal states and transition guards to anyone who guesses the route. There is no authorization layer baked in; add one or gate it behind a dev-only firewall if your route config allows.
Export-and-commit workflow. A durable pattern: run the visualization in CI, dump the DOT/SVG to docs/state-machines/{machine}.svg, and fail the build if the graph has changed without a corresponding docs update. This turns the "picture on a dev server" into a versioned artifact that reviewers can diff. Generate with:
dot -Tsvg machine.dot -o docs/state-machines/order.svg
You need Graphviz installed (apt install graphviz / brew install graphviz). The bundle shells out to it; if dot is missing you get a blank or 500.
Embed in onboarding docs. Because the output is a static image URL, the simplest integration is an <img src="/state-machine/order.svg"> inside your internal wiki or an admin dashboard iframe. This is how most teams actually use it day to day — nobody remembers the route, but everyone bookmarks the rendered diagram.
Pair with config changes in the same PR. The workflow that works: when you add a transition to winzou_state_machine, re-render and include the updated diagram in the PR. Reviewers can visually confirm no orphan states or dangling transitions were introduced. This is a small discipline that catches a surprising number of modeling bugs.
For a Laravel equivalent, replicate the shape not the code. Build an Artisan command state:visualize {machine} that reads your config (a PHP array or attributes on the model), constructs DOT, and writes to storage/app/state-machines/. Keep it out of routes/web.php; expose it only via the CLI. Same value, no Symfony coupling.
It is not a Laravel package — this is the number one gotcha. Composer will happily install it (it is a symfony-bundle type), but nothing will run. Do not attempt to shoehorn it into a Laravel app. If your team is Laravel-only, budget time to write the ~50-line DOT generator yourself; that is less work than fighting the bundle's kernel dependency.
Graphviz binary, not just the PHP package. The most common first-run failure is a 500 with a cryptic "command not found" or an empty response. Confirm dot --version works as the web server user, not just your shell user. Container images frequently ship without it.
Stale release. The last tag is 2022-11-25. Symfony 7 and PHP 8.3+ compatibility is unlikely to be tested. Pin your symfony/* constraints or accept that you may need to patch. If you are on Symfony 7, prefer Symfony's native Workflow component's GraphvizDumper over this bundle — it does the same thing with first-party support.
winzou/state-machine-bundle is the real dependency risk. The upstream package is lightly maintained; if it breaks on your Symfony version, this visualization bundle has no chance. Check the upstream issue tracker before building a workflow around either.
Empty graph = config not loaded. If the visualization renders but shows nothing, the bundle almost certainly cannot see your winzou_state_machine config. Check that the config file is actually loaded for the bundle's environment (debug:config winzou_state_machine), and that the machine key matches what you are requesting.
DOT output is your debugging lever. When the pretty SVG is wrong, fetch the raw DOT. It is far easier to see missing edges or extra nodes in text than in a layout you did not write. Most issues (a state you defined but never transition to, a callback attached to the wrong transition) are visible in three lines of DOT.
Extension points are thin. The bundle is small; expect to override the controller or template via Symfony's standard mechanism (templates/bundles/...) rather than a dedicated extension API. If you need colors per state, annotations on guards, or clustering by aggregate, you will be post-processing the DOT yourself — plan for that.
Do not rely on it for validation. The visualization reflects configuration, not runtime behavior. It will not show you states that are unreachable in practice due to guard conditions, nor transitions that fail because a callback throws. Use it for the shape of the machine; use tests for the behavior.
How can I help you explore Laravel packages today?