php-regex / regex-generator

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

• generator
• fixtures
• testing
• regex
• PCRE

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

README

PHPRegex Generator

Generates sample strings and test cases that a regex matches or rejects.

Part of PHPRegex, released with its siblings under one version number.

Documentation: php-regex.com — the API reference documents generate() end to end.

Features

• Generates a random string the pattern matches, from the parsed AST, and checks it with the running engine
• Reproducible samples: seed the generator, reset the seed, draw again
• Open-ended quantifiers (*, +, {n,}) capped by a configurable repetition limit
• Unicode properties (\p{Lu}), POSIX classes ([[:alpha:]]) and negated classes resolved by asking the running PCRE engine
• Lookaheads and lookbehinds held where they stand; backreferences repeat what their group captured
• Matching and non-matching strings for a pattern, ready for a test suite
• SampleGenerationException when no sample can be built

Installation

composer require php-regex/regex-generator

Requires PHP 8.1+ and php-regex/regex-parser. MIT licensed.

Configuration

• maxRepetition (int, default 3): extra repetitions drawn for *, + and {n,}
• seed (?int, default null, last argument of the SampleGenerator constructor): locks the random source for reproducible samples; each sample drawn starts again from it
• setSeed(int $seed) and resetSeed(): lock the random source later, or unlock it
• PcreEngine $engine (constructor of both generators): the engine asked what a class or a property holds

Usage

A sample the running engine matches: generate() draws from the pattern and checks each draw with preg_match(), padding the sample when an assertion asks for text around it, and throws SampleGenerationException when no draw matches:

use PHPRegex\Generator\SampleGenerator;

echo (new SampleGenerator())->generate('/(?!^)a/'); // "aa"

Visiting the tree draws from the tree alone, unchecked; a sample, made reproducible with a seed:

use PHPRegex\Generator\SampleGenerator;
use PHPRegex\Parser\RegexParser;

$generator = new SampleGenerator(seed: 42);

echo RegexParser::create()->parse('/[A-Z]{3}-\d{4}/')->accept($generator); // "VEL-0403"

Test cases, matching and not, each one checked against the running engine (preg_match() gives 1 on every matching case, 0 on every non-matching one):

use PHPRegex\Generator\TestCaseGenerator;
use PHPRegex\Parser\RegexParser;

$cases = RegexParser::create()->parse('/\d{3}-\d{4}/')->accept(new TestCaseGenerator());

echo $cases['matching'][0];     // "000-0000"
echo $cases['non_matching'][0]; // "00.000"

When no sample can be built, the visitor says why:

use PHPRegex\Generator\Exception\SampleGenerationException;
use PHPRegex\Generator\SampleGenerator;
use PHPRegex\Parser\RegexParser;

try {
    RegexParser::create()->parse('/(?&missing)/')->accept(new SampleGenerator());
} catch (SampleGenerationException $e) {
    echo $e->getMessage(); // "Sample generation for subroutines is not supported."
}

The Toolkit facade checks each sample against the running engine and retries before settling.

Documentation

• Quick start — parse, generate and analyze in one tour
• API reference — the generate() facade: retries, engine checks, error codes
• Visitors — the visitor pattern both generators implement
• Testing and debugging — generated samples in a test workflow
• 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
• Changelog
• Bridges and tools — Laravel, Symfony, CLI, PHPStan and LSP
• 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.