php-regex / regex-generator

2.x-dev 2026-10-03 15:16 UTC

Requires

• php: >=8.2
• php-regex/regex-parser: ^2.0

MIT

• Younes ENNAJI

• generator
• fixtures
• testing
• regex
• PCRE

Published on Packagist.org on 2026-10-04 21:27 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.

Features

• Generates a random string the pattern matches, from the parsed AST
• 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.2+ and php-regex/regex-parser. MIT licensed.

Configuration

• maxRepetition (int, default 3): extra repetitions drawn for *, + and {n,}
• setSeed(int $seed) and resetSeed(): lock the random source for reproducible samples
• PcreEngine $engine (constructor of both generators): the engine asked what a class or a property holds

Usage

A sample, made reproducible with a seed:

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

$generator = new SampleGenerator();
$generator->setSeed(42);

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

Test cases, matching and not:

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\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

• 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.