jonaspardon/mermaid-php
Generate Mermaid diagrams from PHP with a fluent API. Build flowcharts, sequence diagrams, and more as strings for docs, dashboards, or Markdown—no JavaScript required.
mermaid-php is a text generator: you build a diagram with a fluent PHP API and get back a Mermaid definition string. It does not render anything — that happens in the browser, in your IDE, or via mermaid-cli/Kroki.
composer require jonaspardon/mermaid-php
v1.0.1 is purely a compatibility release (Laravel 11 support via @pieterclaerhout); the public API is unchanged from v1.0.0. There is nothing to migrate, but if you had pinned ^1.0.0 on a Laravel 11 app and previously needed --with-all-dependencies or a fork to bypass the illuminate/support constraint, a plain composer update now resolves cleanly. Note Laravel 11 implies PHP 8.2+, so confirm your platform requirement before bumping.
Where to look first:
src/ root — each diagram type is a class with add*/node/edge style methods and a __toString()/render step. Skim one class end-to-end; they follow the same shape.tests/ — the fastest feedback loop is a Pest/PHPUnit test that echoes the output.First use case: generate an ER diagram of an existing schema so new hires stop asking "how do these tables relate?". Put it in an Artisan command, write the output to docs/diagrams/schema.mmd, commit it, and point your README at a rendered image.
Commit diagrams, not code paths. The highest-value pattern is a scheduled/CI job that regenerates .mmd files into docs/ and lets the PR diff show the change. Mermaid definitions are deterministic strings, so they diff beautifully in code review — a new pivot table shows up as three added lines.
Derive ER diagrams from the schema, not from memory. Laravel 11 ships Schema::getTables() and Schema::getColumns(), which pairs naturally with this package: loop tables, emit one entity per table, one relation per foreign key. Same idea works for Eloquent relations via reflection, but the schema route is more reliable because it can't drift from what's actually in the database.
Model your state machines in one place. If you have a status enum with transitions, generate the stateDiagram from the same enum/transition map your application uses. One source of truth, and the diagram in the docs can never be stale.
Two rendering strategies, pick per audience:
.mmd files and render with mermaid-cli (mmdc) in CI, or link to the GitHub blob view (GitHub renders Mermaid in .md fences natively).<pre class="mermaid">{{ $definition }}</pre> plus the mermaid.js bundle, and a route that returns the raw definition as text/plain so the VS Code Mermaid extension and mmdc can consume it directly.Wrap it in a small service class. Rather than sprinkling builders through controllers, expose App\Support\DiagramBuilder::schema() / ::workflow(string $name). You get a place to set defaults (direction, theme, securityLevel) and a single seam to mock in tests. A config file (config/diagrams.php) for output paths and default theme keeps the commands tidy.
Snapshot-test the output. $this->assertSame(file_get_contents(base_path('tests/fixtures/schema.mmd')), $command->output()) catches accidental label changes. Combine with CI rendering so a syntactically broken diagram fails the build rather than the reader's browser.
PHP produces text, not pictures. Budget for a renderer: mermaid.js on the frontend, mmdc (needs Node + headless Chromium) in CI, or a Kroki endpoint. If you expected ->png(), that's not this package. Cache rendered SVGs in storage/app/mermaid keyed by a hash of the definition so page loads don't re-render.
{{ }} collides with Blade. Mermaid's hexagon node syntax is id{{label}}, and Blade will happily try to echo it. Wrap the diagram block in @verbatim ... @endverbatim or keep definitions in a .mmd file and @include-adjacent-load it. This is the single most common "why is my diagram broken" report.
Sanitise labels aggressively. Quotes, semicolons, #, <, > and unbalanced parentheses all break the parser. If any label comes from user input or a database comment, strip/escape it in your wrapper. This is also an XSS vector: mermaid renders HTML in labels by default, so keep securityLevel: 'strict' on the client and never inject raw user strings into a definition you render.
Node IDs are not free-form. Hyphens, spaces and dots in IDs collide with edge syntax (A-->B), producing baffling parse errors. Slugify IDs to [A-Za-z0-9_] and keep the human-readable text in the label.
Sort before you generate. Eloquent collections and getTables() results can come back in a different order between environments; unsorted output turns a one-line schema change into a 200-line diff. ->sortKeys() / ksort() your table and relation lists.
Laravel 11 users must still check the PHP constraint. v1.0.1 widened illuminate/support, but if a dependency of yours pins an older illuminate/*, Composer will silently keep the old resolution. Verify with composer why jonaspardon/mermaid-php after updating; --with-all-dependencies is your friend.
Pin the major, watch the minors. The package only hit 1.0 recently and the contributor base is small. ^1.0 is reasonable; read the changelog before minors, and snapshot-test the output so an upstream formatting tweak doesn't quietly rewrite your committed diagrams.
Keep diagrams small and purpose-built. Generated ER diagrams over 30 tables are unreadable regardless of the tool. Generate per-domain diagrams (billing, auth, content) by filtering tables, rather than one mega-graph.
Be careful with production schema dumps. Auto-generated diagrams leak real table and column names into a public repo. Gate the command behind an allowlist or run it against a sanitised schema.
No Blade component ships with the package. You'll write the <pre class="mermaid"> partial, the route, and the asset loading yourself — roughly 20 lines, but plan for it rather than hunting for a directive that isn't there.
How can I help you explore Laravel packages today?