README

PHPRegex CLI

The regex console: seventeen subcommands to parse, explain, validate, lint, hunt ReDoS, transpile, diagram and debug patterns — also shipped as a self-updating regex.phar.

Documentation: php-regex.com — the CLI guide takes the seventeen subcommands one by one.

Features

• Lints a whole codebase: patterns extracted from preg_* calls, RegexIterator and filter_var(), eight library presets and your own helpers, followed through the constants, variables and properties that hold them and the concatenations, interpolations and sprintf() calls that build them, then judged by 53 lint rules; the pattern arguments built at run time are counted, and --report-dynamic lists them.
• ReDoS verdicts proven on a model of PCRE's backtracking, with the input that triggers a vulnerable pattern; confirmed mode replays it on the running PCRE — plus a benchmark command.
• Automata comparison of two patterns: intersection, subset, equivalence, with counter-examples.
• Transpiles PCRE patterns to JavaScript, HTML pattern attributes and Python; renders the AST as text or SVG and the NFA as DOT or Mermaid.
• CI-ready reports in five formats with three stable exit codes, and a self-updating regex.phar.

Installation

composer require --dev php-regex/regex-cli

The binary is vendor/bin/regex and requires PHP 8.1+.

Standalone phar

curl -Ls https://github.com/php-regex/php-regex/releases/latest/download/regex.phar -o ~/.local/bin/regex && chmod +x ~/.local/bin/regex
regex self-update

The phar is built from the release tag by a GitHub Actions workflow and attested: gh attestation verify ~/.local/bin/regex --repo php-regex/php-regex checks that yours is that build.

Commands

Configuration

Global options:

lint reads defaults from regex.json or regex.dist.json in the working directory — paths, excludes, extraction interop, which checks run. Command-line options win; --output <file> writes the report to a file.

Every command exits 0 when it found nothing wrong, 1 when the patterns or files it judged have a problem, 2 when the command line or configuration cannot be used.

Usage

Validate a pattern — the hello world of the console (outputs below come from --no-visuals runs):

vendor/bin/regex validate '/^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$/i' --no-visuals
#   Pattern: /^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$/i
#   Status: OK

vendor/bin/regex validate '/(?<=a+)b/' --no-visuals  # exits 1
#   Pattern: /(?<=a+)b/
#   Status: INVALID
#   Lookbehind is unbounded. PCRE requires a bounded maximum length.
# Line 1: (?<=a+)b
#         ^

analyze adds a ReDoS report before explaining the pattern:

vendor/bin/regex analyze '/(a+)+$/' --no-visuals
#   Pattern: /(a+)+$/
#   Parse: OK
#   Status: OK
#   Status: Exponential backtracking (proven)
#   Severity: CRITICAL (score 10)
#   Mode: THEORETICAL
#   Confidence: MEDIUM
#   Attack: "a" x n . "!"
#   Hotspot:   1-3

lint walks PHP sources and reports in five formats; with --format=github each finding becomes an annotation GitHub renders natively:

vendor/bin/regex lint src/ --format=github --no-visuals
# Target: PHP 8.2, PCRE2 10.40 (composer.json require.php)
# ::notice file=src/demo.php,line=3,col=12,title=Lint (regex.lint.group.quantifiedCapture)::Quantified capturing group "(...)" with "+": only the last iteration's capture is retained.%0ASuggestion: Use a non-capturing group (?:...) for the repetition and capture the whole match, or restructure the pattern.%0ARead more: https://php-regex.com/reference/rules/#quantified-capturing-group
# ::warning file=src/demo.php,line=3,col=12,title=Lint (regex.lint.quantifier.nested)::Nested quantifiers can cause catastrophic backtracking.%0ASuggestion: Consider atomic groups (?>...) or possessive quantifiers — verify the rewrite still matches everything you need.%0ARead more: https://php-regex.com/reference/rules/#nested-quantifiers-redos-risk

transpile writes the pattern for another engine:

vendor/bin/regex transpile '/[a-z]+\d/' --target=js --no-visuals
#   Target: JAVASCRIPT
#   Source: /[a-z]+\d/
#   ...
#   Constructor:
#     new RegExp("[a-z]+\\d", "")

Documentation

• Quick start — from installation to a first analysis.
• CLI guide — every subcommand in depth, the lint configuration file, CI recipes.
• ReDoS guide — the risky shapes, the two analysis modes, mitigation.
• Backward compatibility — the promise that holds across 2.x.

Resources

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

Sponsors

If PHPRegex saves you time, consider sponsoring its maintenance.

License

MIT. See LICENSE.