- What is jonaspardon/mermaid-php used for?
- It is a PHP library that builds Mermaid.js diagram definitions through a fluent, object-oriented API, returning them as plain strings. You can use it for flowcharts, sequence diagrams, ER diagrams derived from schema introspection, Gantt charts, and workflow state machines. It is aimed at server-side, deterministic diagram generation rather than free-form user-authored diagrams. The output can be consumed by any Mermaid renderer, including a front-end bundle or the Mermaid CLI.
- How do I install mermaid-php in a Laravel application?
- Install it with composer require jonaspardon/mermaid-php. The package ships a service provider with auto-discovery and a facade for the builder, so no manual registration is needed in Laravel. A publishable config file is available if you want to customise defaults.
- Which Laravel and PHP versions does this package support?
- The package targets Laravel 10 and Laravel 11 with a PHP 8.1+ floor according to its integration assessment. Version 1.0.1 is a patch release whose main substance is adding Laravel 11 support, and it does not disturb Laravel 10 compatibility. You should still verify the exact composer.json constraints against your own support matrix before adopting it.
- Do I need Node.js to use mermaid-php?
- No. If you only need Mermaid syntax as a string, the library is pure PHP and has no Node requirement. Node.js, @mermaid-js/mermaid-cli, and Chromium are only needed for the optional server-side rendering path to PNG or SVG.
- Can mermaid-php render diagrams to PNG or SVG on the server?
- Yes, it supports optional rendering to image or SVG through the Mermaid CLI (mmdc). That path requires Node.js plus @mermaid-js/mermaid-cli, which in turn pulls in Chromium and Puppeteer, so it is usually best handled in a dedicated worker or sidecar container. The real integration cost is that runtime dependency, not the PHP package itself.
- Is it safe to build diagrams from user-supplied or third-party data?
- Be careful. If diagram labels are interpolated from untrusted input, Mermaid syntax injection and downstream XSS in rendered SVG output are real risks. The package does not take responsibility for escaping or sanitising those values, so you must implement escaping and SVG sanitisation yourself. If diagrams are user-authored or free-form, a front-end editor is a better fit than a PHP builder.
- How does mermaid-php compare with writing Mermaid strings manually or using a JavaScript library?
- Writing raw Mermaid strings works but scatters unescaped syntax across Blade templates, docs generators, and markdown. This package gives you a typed, fluent builder and a single place to centralise escaping and future swaps. A JavaScript library or mermaid.live is still the better choice when users need to author diagrams interactively in the browser.
- Is jonaspardon/mermaid-php actively maintained and production-ready?
- It has a single primary maintainer, a low release cadence, and pre-2.0 semantics, so the long-term maintenance risk is the main concern. The 1.0.1 patch itself carries effectively zero marginal risk because it only widens Laravel 11 support. Keeping generation behind a thin internal interface makes the package easy to replace if maintenance lapses.
- How should I test diagram generation in a Laravel app?
- If you only generate Mermaid syntax, assert on the returned string or use snapshot tests, and you can keep Node out of your CI pipeline entirely. If you render server-side, pin the Mermaid CLI version and treat upgrades as tested changes, since the generated syntax is only as portable as the renderer's Mermaid version. Also verify the package's PHP floor and Laravel 11 Testbench coverage on your own matrix rather than relying on release notes.
- Can I render the diagrams in the browser instead of on the server?
- Yes, and for many Laravel apps that is the simpler option. Use the package to produce the Mermaid source string, then hand it to a client-side Mermaid bundle for rendering in dashboards or documentation. This removes the Node and Chromium dependency from your runtime image entirely and keeps the rendering work on the user's machine.