php-regex / regex-explain

2.x-dev 2026-10-27 06:25 UTC

Requires

• php: >=8.1
• ext-mbstring: *
• php-regex/regex-parser: 2.x-dev

MIT

• Younes ENNAJI

• highlight
• regex
• PCRE
• diagram
• explain
• railroad

Published on Packagist.org on 2026-10-27 10:05 UTC

README

PHPRegex Explain

Explains, highlights and draws regex ASTs: plain text and HTML explanations, console and HTML highlighting, ASCII trees, Mermaid and railroad diagrams.

Every class here is a node visitor: parse once with regex-parser, then walk the AST with accept(). There is nothing to configure.

Documentation: php-regex.com — the visitor reference is the class-by-class tour.

Features

• Plain-English explanation, one line per construct (TextExplainer)
• The same explanation as HTML, each node carrying a title tooltip (HtmlExplainer)
• Terminal syntax highlighting in 24-bit ANSI colors (Highlighter\ConsoleHighlighter)
• Web syntax highlighting as regex-token spans you style yourself (Highlighter\HtmlHighlighter)
• ASCII tree of the AST, for logs and code review (AsciiTreeRenderer)
• Mermaid flowchart source, for Markdown and docs sites (MermaidRenderer)
• Standalone railroad-diagram SVG with its stylesheet embedded (RailroadSvgRenderer)
• Covers the parser's whole PCRE node set: groups, quantifiers, class-set operations, conditionals, subroutines, callouts

Installation

composer require php-regex/regex-explain

Requires PHP 8.1+ and php-regex/regex-parser at the same version, pulled in automatically.

Usage

Explain a pattern in plain English:

use PHPRegex\Explain\TextExplainer;
use PHPRegex\Parser\RegexParser;

$ast = RegexParser::create()->parse('/[A-Z][a-z]+\d*/');

echo $ast->accept(new TextExplainer());
// Regex matches
//   Character Class: any character in [ Range: from 'A' to 'Z' ]
//   Character Class: any character in [ Range: from 'a' to 'z' ] (one or more times)
//   Character Type: A digit: [0-9] (zero or more times)

Print the AST itself as a tree:

use PHPRegex\Explain\AsciiTreeRenderer;

$ast = RegexParser::create()->parse('/(?<year>\d{4})-\d{2}/');

echo $ast->accept(new AsciiTreeRenderer());
// Regex
// \-- Sequence
//     |-- Group (named) name="year"
//     |   \-- Quantifier ({4}, greedy)
//     |       \-- CharType (\d)
//     |-- Literal ('-')
//     \-- Quantifier ({2}, greedy)
//         \-- CharType (\d)

Highlight the pattern instead of explaining it — ANSI for a terminal, span classes for a web page:

use PHPRegex\Explain\Highlighter\ConsoleHighlighter;
use PHPRegex\Explain\Highlighter\HtmlHighlighter;

$ast = RegexParser::create()->parse('/\d{2,}/');

// wraps each token as \e[38;2;R;G;Bm...\e[0m (true color)
echo $ast->accept(new ConsoleHighlighter());

echo $ast->accept(new HtmlHighlighter());
// <span class="regex-token regex-type regex-escape">\d</span><span class="regex-token regex-quantifier">{2,}</span>

Render an explanation ready for a web page — the title attribute holds the detail:

use PHPRegex\Explain\HtmlExplainer;

echo RegexParser::create()->parse('/\d{3}-\d{4}/')->accept(new HtmlExplainer());
// <div class="regex-explain">
// <strong>Regex matches:</strong>
// <ul><li><span title="Character Type: A digit: [0-9] (exactly 3 times)">Character Type: <strong>\d</strong> (A digit: [0-9])</span> (exactly 3 times)</li>…
// </ul>
// </div>

Draw the pattern — Mermaid source for a docs page, a complete SVG for anywhere else:

use PHPRegex\Explain\MermaidRenderer;
use PHPRegex\Explain\RailroadSvgRenderer;

$ast = RegexParser::create()->parse('/a(b|c)*/');

echo $ast->accept(new MermaidRenderer());
// graph TD;
//     node0["Regex: none"]
//     node1["Sequence"]
//     node2["Literal: a"]
//     node1 --> node2
//     node3["Quantifier: *"]
//     … remaining nodes and edges …

file_put_contents('railroad.svg', $ast->accept(new RailroadSvgRenderer()));
// a complete XML document: an <svg> root with its stylesheet embedded

Documentation

• Quick start — explain and highlight in the opening tour
• Visitor reference — every Explain class, with examples
• CLI guide — the regex explain, highlight and diagram commands
• Backward compatibility — what stays stable across releases

Resources

• Upgrading from 1.x — moving from yoeunes/regex-parser 1.3 to 2.0, every change that needs one on your side
• All PHPRegex packages — one repo, one version number
• Changelog
• Report issues and send pull requests in the main repository

Sponsors

If PHPRegex saves you time, consider sponsoring its maintenance.

License

MIT. See LICENSE.