30335023763

Committed 23 Jul 2026 07:33PM UTC coverage: 91.755%. Remained the same

Build # 30335023763

Build Type

push

github

Committed by

web-flow

Commit Message

feat: add Sequence Diagram support (#10) (#33)

## Summary

Adds first-class Mermaid `sequenceDiagram` support to the library,
following the same fluent, object-oriented style as the existing
`Graph`/`Timeline` families. Requested in #10.

A sequence diagram is modeled as an **ordered stream of statements with
nesting** (not two flat sets like `Graph`). A tiny `Statement` interface
(`render(int $shift): string`, extends `\Stringable`) is implemented by
every body element; participants/boxes form a header region; the
`SequenceDiagram` container renders header + ordered body and plugs into
the existing `Render`/`Helper` machinery.

## What's covered (full `sequenceDiagram` syntax)

- **Participants / actors** — aliases, `safeMode` (md5 ids, like
`Node`), repeatable per-participant `link()`
- **Messages** — all 10 arrow types, inline activation (`+`/`-`,
mutually exclusive) and explicit `activate`/`deactivate`
- **Notes** — `left of` / `right of` / `over` (one or two participants)
- **Lifecycle** — `create` / `destroy`; **comments** (`%%`)
- **Boxes** — participant grouping with optional color
- **Control blocks** — `loop`, `opt`, `break`, `rect` (single-section)
and `alt`/`else`, `par`/`and`, `critical`/`option` (multi-section),
arbitrarily nestable
- **Container** — title frontmatter, `autonumber`, `getParticipant()`,
`addMessageByIds()` (throws on unknown id), `renderHtml()`,
`getLiveEditorUrl()`

## Notes

- The `break` block class is named **`BreakBlock`** — `break` is a
reserved word in PHP, so `class Break` is a parse error. It still emits
the Mermaid `break` keyword.
- `Render::html()` / `Helper::getLiveEditorUrl()` union types widened to
accept `SequenceDiagram`.
- README updated with the new diagram type and a runnable example.

## Testing

- `tests/SequenceDiagramTest.php`: 23 tests, 58 assertions — every arrow
type, activation, notes, lifecycle, comments, boxes/links, all blocks +
nesting, container ordering, `addMessageByIds` errors, and an ... (continued)

Coverage Stats

153 of 158 new or added lines in 16 files covered. (96.84%)

13 existing lines in 2 files now uncovered.

690 of 752 relevant lines covered (91.76%)

79.63 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

93.33

/src/Helper.php

<?php

/**
 * JBZoo Toolbox - Mermaid-PHP.
 *
 * This file is part of the JBZoo Toolbox project.
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 *
 * @license    MIT
 * @copyright  Copyright (C) JBZoo.com, All rights reserved.
 * @see        https://github.com/JBZoo/Mermaid-PHP
 */

declare(strict_types=1);

namespace JBZoo\MermaidPHP;

use JBZoo\MermaidPHP\ClassDiagram\ClassDiagram;
use JBZoo\MermaidPHP\ERDiagram\ERDiagram;
use JBZoo\MermaidPHP\SequenceDiagram\SequenceDiagram;
use JBZoo\MermaidPHP\Timeline\Timeline;

final class Helper
{
    public static function escape(string $text): string
    {
        $text = \trim($text);
        $text = \htmlentities($text, \ENT_COMPAT);
        $text = \str_replace(['&', '#lt;', '#gt;'], ['#', '<', '>'], $text);

        return "\"{$text}\"";
    }

    public static function getId(string $userFriendlyId): string
    {
        return \md5($userFriendlyId);
    }

    public static function getLiveEditorUrl(ClassDiagram|ERDiagram|Graph|SequenceDiagram|Timeline $mermaid): string
    {
        $json = \json_encode([
            'code'    => (string)$mermaid,
            'mermaid' => [
                'theme' => 'forest',
            ],
        ]);

        if ($json === false) {
            throw new \RuntimeException('Can\'t encode graph to JSON');
        }

        $params = \base64_encode($json);

        return "https://mermaid-js.github.io/mermaid-live-editor/#/edit/{$params}";
    }
}

1	<?php
2
3	/**
4	* JBZoo Toolbox - Mermaid-PHP.
5	*
6	* This file is part of the JBZoo Toolbox project.
7	* For the full copyright and license information, please view the LICENSE
8	* file that was distributed with this source code.
9	*
10	* @license MIT
11	* @copyright Copyright (C) JBZoo.com, All rights reserved.
12	* @see https://github.com/JBZoo/Mermaid-PHP
13	*/
14
15	declare(strict_types=1);
16
17	namespace JBZoo\MermaidPHP;
18
19	use JBZoo\MermaidPHP\ClassDiagram\ClassDiagram;
20	use JBZoo\MermaidPHP\ERDiagram\ERDiagram;
21	use JBZoo\MermaidPHP\SequenceDiagram\SequenceDiagram;
22	use JBZoo\MermaidPHP\Timeline\Timeline;
23
24	final class Helper
25	{
26	public static function escape(string $text): string
27	{
28	$text = \trim($text);	312✔
29	$text = \htmlentities($text, \ENT_COMPAT);	312✔
30	$text = \str_replace(['&', '#lt;', '#gt;'], ['#', '<', '>'], $text);	312✔
31
32	return "\"{$text}\"";	312✔
33	}
34
35	public static function getId(string $userFriendlyId): string
36	{
37	return \md5($userFriendlyId);	24✔
38	}
39
40	public static function getLiveEditorUrl(ClassDiagram\|ERDiagram\|Graph\|SequenceDiagram\|Timeline $mermaid): string
41	{
42	$json = \json_encode([	12✔
43	'code' => (string)$mermaid,	12✔
44	'mermaid' => [	12✔
45	'theme' => 'forest',	12✔
46	],	12✔
47	]);	12✔
48
49	if ($json === false) {	12✔
UNCOV 50	throw new \RuntimeException('Can\'t encode graph to JSON');	×
51	}
52
53	$params = \base64_encode($json);	12✔
54
55	return "https://mermaid-js.github.io/mermaid-live-editor/#/edit/{$params}";	12✔
56	}
57	}

JBZoo / Mermaid-PHP / 30335023763

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous