Mermaid Php Laravel Package

Technical Evaluation

Package: jonaspardon/mermaid-php — a PHP library that builds Mermaid.js diagram definitions via a fluent, object-oriented API, with optional rendering to image/SVG through the Mermaid CLI (mmdc).

Architecture fit: Reasonable for server-side, deterministic diagram generation where diagrams are derived from application data (ER diagrams from schema introspection, flowcharts from workflow state machines, sequence diagrams from job pipelines, Gantt output for delivery reporting). It fits Laravel cleanly: service provider with package auto-discovery, a facade for the builder, and a publishable config file. It is a poor fit for user-authored or free-form diagrams — that workload belongs in a front-end editor (mermaid.live, Mermaid + a JS bundle), not in PHP.

Integration feasibility: Low-effort to adopt in "syntax generation only" mode — a composer require, auto-discovered provider, and the fluent builder returns a Mermaid string that any renderer (including the front end) can consume. Rendering to PNG/SVG server-side raises the effort: it requires Node.js plus @mermaid-js/mermaid-cli (and therefore Chromium/Puppeteer) in the runtime image or a sidecar container. That dependency, not the package, is the real integration cost.

Technical risk:

• Bus factor / maturity: single primary maintainer, low release cadence, pre-2.0 semantics. v1.0.1 is a patch that only adds Laravel 11 support — no breaking changes, so the marginal risk of this release is effectively zero; the standing risk is long-term maintenance.
• Runtime coupling (rendering path only): Node/Chromium presence, headless browser sandboxing, cold-start latency, and image size in the container. Container hardening (no --no-sandbox in production) is a security consideration that must be owned explicitly.
• Input trust: if diagram labels are interpolated from user or third-party data, Mermaid syntax injection and downstream XSS in SVG output are real. Escaping and output sanitisation are on us, not the package.
• Version drift: generated syntax is only as portable as the Mermaid version the renderer uses. Pin the Mermaid CLI version and treat upgrades as tested changes.
• Ambiguity to close: confirm the target PHP version floor and whether the Laravel 11 support is a composer.json constraint widening only or includes Testbench/CI coverage for 11.

Key questions:

1. Do we need server-side raster/SVG rendering at all, or is delivering Mermaid source to a client-side renderer sufficient? (The latter removes the Node dependency entirely.)
2. If rendering server-side: dedicated worker/sidecar vs. in-app Node binaries — who owns the image and its Chromium patching?
3. Are diagram inputs ever user-supplied? If yes, what is the escaping and SVG sanitisation policy?
4. What is our PHP/Laravel support matrix, and does the package's constraint set actually match it (verify beyond the PR title)?
5. Acceptable exit cost: how much of our code touches the fluent builder vs. plain Mermaid strings? Keeping generation behind a thin internal interface makes the package replaceable.

Integration Approach

Stack fit: Laravel 10/11, PHP 8.1+. Composer-installed, auto-discovered provider, optional config publish. No database, queue, or cache requirements of its own — it is a pure library, which is exactly what we want from a dependency of this size.

Migration path: Greenfield — no migration required. If we have ad-hoc Mermaid strings scattered in Blade templates, docs generators, or markdown, treat this as a consolidation opportunity: move those strings behind the package's builder in a single DiagramService, which gives us one place to escape labels and one place to swap the library out later.

Compatibility: v1.0.1 adds Laravel 11 support (contributed PR), which is the entire substance of this release — safe to adopt on 11, and it does not disturb 10. Verify on our matrix: PHP version floor, Laravel 11 Testbench coverage, and that composer update does not drag an unexpected transitive change. Since the constraint widening is the only change, pin ^1.0.1 and let CI prove it.

Sequencing:

1. Spike (1–2 days): proof-of-concept in one real reporting view; decide source-only vs. server-side rendering. This decision gates everything downstream.
2. Adopt source-only in the docs/reporting module; no infra change, ship behind a feature flag.
3. If rendering is required: build and harden a renderer container, add a queued job with timeout and cache-keying on the diagram hash, then wire it in.
4. Standardise: one internal facade/service, escaping rules, golden-file tests comparing generated Mermaid source.
5. Defer any use in customer-facing, high-traffic request paths until the renderer path has run in production for a release cycle.

Operational Impact

Maintenance: Minimal for source-only usage — a composer constraint and a semver-major watch. Rendering adds ongoing ownership: Node LTS, Mermaid CLI, and Chromium patching on our cadence, independent of the package's. Budget that as a standing line item, not a one-off setup cost.

Support: Community-only. GitHub issues, no SLA, no commercial backing. Acceptable for internal tooling and documentation output; not acceptable as a hard dependency of a revenue-path feature without the internal abstraction layer described above.

Scaling: Source generation is pure CPU-cheap string building — negligible. Rendering is the bottleneck: headless Chromium is memory-hungry (~hundreds of MB per process) and slow (seconds per diagram, worse on cold start). Required posture: render asynchronously on a queue with a dedicated pool, cache aggressively by hash(mermaid_source + mermaid_version + theme), cap concurrent renderers, and never render inline in a web request.

Failure modes:

• mmdc binary or Chromium missing/misconfigured → runtime exception; fails at deploy, not at build, unless we smoke-test it in CI.
• Render timeout / Chromium crash on large or pathological diagrams → job failure; needs retry with backoff and a documented fallback (serve source plus a client-side renderer).
• Invalid Mermaid syntax emitted by our own code → renders as an error graph or throws; catch with golden-file tests over representative diagrams.
• Mermaid CLI upgrade changes rendering → pin the version; upgrade deliberately with visual diff review.
• Unescaped user text breaks syntax or injects script into SVG → escape at the boundary, sanitise SVG before serving.

Ramp-up: Low. The fluent builder is discoverable and the mental model is just Mermaid syntax, which most engineers already recognise from Markdown tooling — roughly half a day to productive for a mid-level PHP developer, with the real learning curve being diagram design (which diagram type for which question), not the API. Document one internal example per diagram type and the escaping rule; that is enough. The rendering infrastructure, if adopted, is a separate and much steeper ramp — assign it to whoever already owns container builds.