Diagnostics and Error Messages

This comprehensive guide explains how PHPRegex reports errors and warnings, how to read diagnostic output, and how to map diagnostics to fixes.

Table of Contents

Validation Layers

PHPRegex validates patterns through four layers, each catching different types of issues:

Pattern literal
  -> Parse (Lexer + Parser): syntax errors, malformed patterns
  -> Semantic validation: PCRE rules, group and reference checks
  -> Runtime validation (optional): preg_match compilation
  -> Linting & analysis: ReDoS, performance, best practices

Examples by layer:

• Parse: unbalanced brackets [a-z, invalid escapes \x, missing delimiters foo
• Semantic: unbounded lookbehind (?<=a+), backreference to non-existent group \2, duplicate group names
• Runtime: engine-specific compilation errors
• Linting & analysis: nested quantifiers (a+)+, useless flags /\d+/i, redundant groups (?:foo)

Reading Diagnostics

ValidationResult Fields

When you call Regex::validate(), you get a ValidationResult object:

use PHPRegex\Toolkit\Regex;

$result = Regex::create()->validate('/[unclosed/');

if (!$result->isValid) {
    // Access all diagnostic information
    echo $result->isValid;          // false
    echo $result->error;            // "Unclosed character class "]" at end of input."
    echo $result->errorCode->value; // "regex.charclass.unclosed"
    echo $result->offset;           // 9
    echo $result->caretSnippet;     // See below
    echo $result->hint;             // null: no hint for this one
    echo $result->complexityScore;  // 0
    echo $result->category->value;  // "syntax"
}

Field Reference Table:

Understanding Caret Snippets

The caretSnippet shows exactly where the error occurred:

Pattern: [unclosed
          ^

This visual representation helps you quickly locate and fix issues.

CLI Examples

The regex binary ships with php-regex/regex-cli: composer require --dev php-regex/regex-cli (see Quick Start).

Validation Error with Caret

vendor/bin/regex --no-ansi validate '/(?<=a+)b/'

Output (after the version and runtime header):

  [1/1] Validating pattern
  Pattern
      → /(?<=a+)b/
  Status : INVALID
  Lookbehind is unbounded. PCRE requires a bounded maximum length.
Line 1: (?<=a+)b
        ^

What to notice:

1. Status : INVALID indicates failure
2. The message explains the problem
3. The caret (^) shows exact position

Successful Validation

vendor/bin/regex --no-ansi validate '/^[a-z]+$/'

Output (after the version and runtime header):

  [1/1] Validating pattern
  Pattern
      → /^[a-z]+$/
  Status : OK

ReDoS Analysis Summary

vendor/bin/regex --no-ansi analyze '/(a+)+$/'

Output:

  [1/4] Parsing pattern
  Pattern
      → /(a+)+$/
  Parse : OK

  [2/4] Validation
  Status : OK

  [3/4] ReDoS analysis
  Status     : Exponential backtracking (proven)
  Severity   : CRITICAL (score 10)
  Mode       : THEORETICAL
  Confidence : MEDIUM
  Attack: "a" x n . "!"
  Hotspot:   1-3

  [4/4] Explanation
Regex matches
  Start Quantified Group (one or more times)
    Capturing group
            'a' (one or more times)
    End group
  End Quantified Group
  Anchor: the end of a line

What to notice:

• Parse and Validation show structural validity
• The ReDoS Status is the verdict: (proven) when the backtracking model decided, (heuristic) when structural rules did
• Attack is the input that triggers it, as PHP: str_repeat("a", $n) . "!"
• Explanation translates AST to plain language

CLI Output Types

Lint Diagnostics

Linting finds issues beyond validity — performance, security, and best practices.

CLI Lint Output

vendor/bin/regex lint app/ --no-ansi

Output (trimmed):

  [1/2] Scanning files
  Scanned 1 files, found 1 patterns.

  [2/2] Analyzing patterns
  app/Service/Validator.php:9:33
      → /^(?:[0-9]+\s?)+$/
    WARN Nested quantifiers can cause catastrophic backtracking.
         ↳ Consider atomic groups (?>...) or possessive quantifiers — verify the rewrite still matches everything you need.
    TIP
         - /^(?:[0-9]+\s?)+$/
         + /^(?:\d+\s?)+$/

  PASS 1 warnings found, 1 optimizations available.

Each finding opens on file:line:column and the pattern, then one line per issue, its badge (FAIL, WARN or INFO) and its hint, and a TIP for a shorter equivalent. Warnings alone leave the exit code at 0.

JSON Output for CI

vendor/bin/regex lint app/ --format=json

Output:

{
    "target": {
        "php": "8.4.26",
        "pcre": "10.49",
        "source": "running PHP",
        "range": [
            {
                "php": "8.4.26",
                "pcre": "10.49"
            }
        ]
    },
    "stats": {
        "errors": 0,
        "warnings": 1,
        "optimizations": 1,
        "redos_errors": 0,
        "infos": 0,
        "lint_errors": 0,
        "parser_fallbacks": 0
    },
    "results": [
        {
            "file": "app/Service/Validator.php",
            "line": 9,
            "column": 33,
            "file_offset": 147,
            "source": "preg_match()",
            "pattern": "/^(?:[0-9]+\\s?)+$/",
            "location": null,
            "issues": [
                {
                    "severity": "warning",
                    "file": "app/Service/Validator.php",
                    "line": 9,
                    "column": 33,
                    "file_offset": 147,
                    "position": 1,
                    "issue_id": "regex.lint.quantifier.nested",
                    "message": "Nested quantifiers can cause catastrophic backtracking.",
                    "hint": "Consider atomic groups (?>...) or possessive quantifiers ...",
                    "tip": null,
                    "source": "preg_match()",
                    "validation": null,
                    "analysis": null,
                    "target": null
                }
            ],
            "optimizations": [
                {
                    "file": "app/Service/Validator.php",
                    "line": 9,
                    "column": 33,
                    "file_offset": 147,
                    "optimization": {
                        "original": "/^(?:[0-9]+\\s?)+$/",
                        "optimized": "/^(?:\\d+\\s?)+$/",
                        "changes": [
                            "Optimized pattern."
                        ]
                    },
                    "savings": 3,
                    "source": "preg_match()"
                }
            ]
        }
    ]
}

Issue Fields: every issue carries every key, null when it does not apply.

The JSON output reference lists every key of the report, with its type, and the rules every JSON document follows.

Stats Fields: the JSON report always carries every key, in this order, 0 when there is none:

The console summary names each kind of error apart: 1 invalid patterns, 1 ReDoS errors, 1 lint errors, 2 warnings, 0 optimizations. An invalid pattern is one PCRE refuses to compile; a lint error is a pattern that compiles but that a rule of error severity reports.

Severity in Each Format

Each lint rule declares a severity, and every output format maps it the same way:

An issue of severity error makes regex lint exit with 1; warnings and infos leave 0. In JUnit, a critical problem is an <error> element and an error one a <failure>; a warning or an info is a passing test case that carries the message in system-out. See the severity table for the severity of each rule.

Common Fixes

Quick solutions for frequently encountered diagnostics:

Lookbehind Errors

Problem: Lookbehind is unbounded

Solution: Make the lookbehind bounded, or restart the match after the run

// ERROR: (?<=a+) is unbounded
preg_match('/(?<=a+)b/', $input);

// FIX 1: Use bounded quantifier (variable length needs PCRE2 10.43+, PHP 8.4)
preg_match('/(?<=a{1,10})b/', $input);

// FIX 2: Restart the match after the run
preg_match('/a+\Kb/', $input);  // matches "b" on "aaab"

Backreference Errors

Problem: Backreference to non-existent group

Solution: Ensure the referenced group exists

// ERROR: \2 refers to non-existent group
preg_match('/(\w+)\2/', $input);  // Only one group

// FIX 1: Use correct group number
preg_match('/(\w+)\1/', $input);  // \1 refers to group 1

// FIX 2: Add the missing group
preg_match('/(\w+)(\w+)\2/', $input);  // Now \2 exists

Nested Quantifiers (ReDoS)

Problem: Nested quantifiers detected

Solution: Use atomic groups or simplify

// VULNERABLE: (a+)+ can cause ReDoS
preg_match('/(a+)+$/', $input);

// FIX 1: Use atomic group
preg_match('/(?>a+)+$/', $input);

// FIX 2: Simplify (often equivalent)
preg_match('/a+$/', $input);

Duplicate Group Names

Problem: Duplicate group name

Solution: Use unique names or enable J flag

// ERROR: Duplicate name 'id'
preg_match('/(?<id>\w+)(?<id>\d+)/', $input);

// FIX 1: Use unique names
preg_match('/(?<id>\w+)(?<number>\d+)/', $input);

// FIX 2: Enable J flag for duplicates
preg_match('/(?J)(?<id>\w+)(?<id>\d+)/', $input);

Invalid Quantifier Range

Problem: Invalid quantifier range: min > max

Solution: Swap or fix the range

// ERROR: {5,2} is invalid (min > max)
preg_match('/\d{5,2}/', $input);

// FIX: Swap to {2,5}
preg_match('/\d{2,5}/', $input);

Character Class Pitfalls

Problem: Suspicious ASCII ranges or alternation-like character classes.

Solution: Split ranges or use alternation groups.

// WARNING: Includes punctuation between Z and a
preg_match('/[A-z]/', $input);

// FIX: Split ranges
preg_match('/[A-Za-z]/', $input);

// WARNING: | is literal in []
preg_match('/[error|failure]/', $input);

// FIX: Use alternation
preg_match('/(error|failure)/', $input);

For the same fixes on one table, see the Diagnostics Cheat Sheet.

Error Code Categories

ValidationResult::$category tells which layer refused the pattern:

Error Codes

Every RegexException carries an ErrorCode (RegexException::getErrorCode()), and so does a failed validation (ValidationResult::$errorCode). An invalid option (InvalidRegexOptionException) or a cache failure (CacheException) is no judgement on a pattern and carries none. Lint advice has ids of its own, regex.lint.<area>.<rule> in camelCase (see the lint rule reference): PHPStan reports them as identifiers, and PHPStan identifiers take no underscore. The values are stable: match on the enum case, or on its string value when the code crosses a process boundary (the CLI’s JSON output and the lint problems carry the string).

use PHPRegex\Parser\ErrorCode;
use PHPRegex\Toolkit\Regex;

$result = Regex::create()->validate('/(?<=a+)b/');

if (ErrorCode::LookbehindUnbounded === $result->errorCode) {
    // ...
}

Each value reads regex.<area>.<problem>. The one value without a problem segment is regex.complexity, raised when an analysis runs out of its work budget.

The delimiter follows PHP: it must not be alphanumeric, a backslash or a NUL byte, and the leading whitespace before it (space, tab, newline, carriage return, vertical tab, form feed) is skipped, as PHP does. "\f/a/" is the pattern a; "\0/a/" is refused with regex.delimiter.invalid: Invalid delimiter "\x00". Delimiters must not be alphanumeric, backslash, or NUL byte.

Edit on GitHub Copy as Markdown