README

Fifteen diagram families, from PHP or from Mermaid, rendered to SVG without a browser.

Build a typed model with a fluent builder, or parse a documented Mermaid subset, then render deterministic SVG. No headless browser, no JavaScript runtime, no external binary.

echo Diagram::fromMermaid($source)->toSvg();

The same model renders back to canonical Mermaid, and round-trip tests hold both directions to it. Backed by an extensive test suite and PHPStan at its highest level.

Diagram types · Build from PHP · Parse Mermaid · Render · Theming · Documentation

Installation

composer require atelier/diagram

Requires PHP 8.3 or later. Depends on atelier/svg for output and atelier/layout for spatial maths, both pure PHP.

Quick start

use Atelier\Diagram\Diagram;

$source = <<<'MERMAID'
stateDiagram-v2
    [*] --> Draft
    Draft --> Review: submit
    Review --> [*]: approve
MERMAID;

file_put_contents('order.svg', Diagram::fromMermaid($source)->toSvg());

The grammar is detected from the first significant line. See Getting started.

Fifteen diagram types

Type	Mermaid header	Type	Mermaid header
Flowchart	`flowchart`	Mindmap	`mindmap`
State	`stateDiagram-v2`	Requirement	`requirementDiagram`
Sequence	`sequenceDiagram`	Kanban	`kanban`
Class	`classDiagram`	Block	`block`
ER	`erDiagram`	Architecture	`architecture`
Git graph	`gitGraph`	C4	`C4Context`
Timeline	`timeline`	Venn	builder only
Journey	`journey`

Each page shows the same diagram three ways: its Mermaid source, the equivalent PHP, and the rendered result. Venn diagrams have no text form in this package.

Build from PHP

Every type has a fluent builder reached from the facade, and each one speaks its own domain: states and transitions, participants and messages, commits and branches.

use Atelier\Diagram\Diagram;

$order = Diagram::state()
    ->title('Order lifecycle')
    ->initial('Draft')
    ->transition('Draft', 'Review', 'submit')
    ->transition('Review', 'Approved', 'approve')
    ->transition('Review', 'Draft', 'reject')
    ->final('Approved')
    ->build();

Diagram::of($order)->saveSvg('order.svg');

The builder returns a typed model, not markup, so it can be inspected, tested, and rendered more than once.

Parse Mermaid

Fourteen of the fifteen families parse a deliberately small, exactly specified Mermaid subset. Anything outside it throws a ParseException carrying the offending line number, rather than silently rendering something else.

$diagram = Diagram::fromMermaid($source);   // throws on anything unsupported
$maybe   = Diagram::tryFromMermaid($source); // null instead of an exception

What the parser accepts, the Markdown renderer emits, and round-trip tests hold both sides to it. See Mermaid support.

Render

$diagram = Diagram::fromMermaid($source);

$diagram->toSvg();        // a string of SVG markup
$diagram->saveSvg($path); // the same, written to a file
$diagram->toMermaid();    // canonical Mermaid, back from the model
$diagram->toMarkdown();   // a fenced Mermaid block, for a README

toSvgDocument() hands back an atelier/svg document when the diagram has to compose into a larger drawing. See Renderers.

Theming

Five presets, and every colour, font and spacing value is a field you can override.

use Atelier\Diagram\Theme\Theme;

$diagram->toSvg(Theme::dark());

default, dark, blueprint, mono, and neutral. See Theming.

Documentation

Getting started: install, first diagram, first render.
Every diagram type: compare the fifteen and pick one.
Theming: presets, and the fields each one sets.
Renderers: SVG, Markdown, and canonical Mermaid.
Mermaid support: the accepted subset, grammar by grammar.

The full documentation is published at ateliersvg.com/diagram.

Contributing

Contributions are welcome. Visit the project on GitHub to report a bug, suggest a feature, or open a pull request.

Before submitting code, run:

composer qa   # PHP-CS-Fixer, PHPStan at level max, and PHPUnit

Changes to public behaviour need a test and a documentation update.

Support

Bug reports, security disclosures, and contribution guidelines are collected at ateliersvg.com/support.

Atelier is maintained by Simon André. Sharing the package or starring it on GitHub helps more than you would think.

License

Atelier Diagram is released under the MIT License.

atelier / diagram

Maintainers

Package info

Fund package maintenance!

Statistics

Security