php-regex / regex-transpiler

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

Requires

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

MIT

• Younes ENNAJI

• javascript
• regex
• python
• PCRE
• transpiler

Published on Packagist.org on 2026-10-04 21:27 UTC

README

PHPRegex Transpiler

Transpiles PCRE patterns to JavaScript and Python regular expressions, with the losses reported.

Features

• Two targets, javascript (alias js) and python (alias py), each producing a paste-ready literal and a constructor call
• Dialect rewrites: (?P<name>) becomes (?<name>) in JavaScript, \k<name> becomes (?P=name) in Python, \h and \v become character classes, atomic groups are emulated in Python
• Flags are mapped per target: JavaScript keeps i, m, s, u, gains u when Unicode escapes need it, and has /x applied then dropped; Python keeps i, m, s, x and spells flags inline or as re constants
• Warnings list every rewrite to review; notes list run-time caveats, such as ASCII-based \w in JavaScript
• A construct the target cannot express — a possessive quantifier, \p{...} in Python — throws a TranspileException carrying the position in the pattern

Installation

composer require php-regex/regex-transpiler

PHP 8.2 or newer. php-regex/regex-parser is pulled in automatically.

Configuration

transpile() takes an optional TranspileOptions object: allowLookbehind (bool, default true) — false makes lookbehind throw for JavaScript targets.

Usage

A PCRE pattern with a named group and a backreference, for a JavaScript codebase:

use PHPRegex\Parser\RegexParser;
use PHPRegex\Transpiler\Transpiler;

$transpiler = new Transpiler(RegexParser::create());
$result = $transpiler->transpile('/(?P<word>\w+)\k{word}/i', 'javascript');

echo $result->literal;  // /(?<word>\w+)\k<word>/i
echo $result->notes[0]; // JavaScript \w and \b are ASCII-based; Unicode word boundaries may differ.

For Python, the literal is a raw string carrying the flags inline, and the constructor is a re.compile() call:

$result = $transpiler->transpile('/(?P<word>\w+)\k<word>/i', 'python');

echo $result->literal;     // r'(?i)(?P<word>\w+)(?P=word)'
echo $result->constructor; // re.compile(r'(?P<word>\w+)(?P=word)', re.IGNORECASE)

Every rewrite is reported, and what a target cannot express is refused rather than approximated:

$result = $transpiler->transpile('/\p{L}+/', 'javascript');

echo $result->literal;     // /\p{L}+/u
echo $result->warnings[0]; // Added /u for Unicode property escapes.

try {
    $transpiler->transpile('/a++/', 'javascript');
} catch (\PHPRegex\Transpiler\TranspileException $e) {
    echo $e->getMessage(); // Possessive quantifiers are not supported in JavaScript.
}

Documentation

• API reference — the transpile() entry point and the TranspileResult fields
• CLI guide — the regex transpile command, its --target option and its exit codes
• Backward compatibility promise — what stays stable across releases

Resources

• Documentation
• The parsing core it builds on: regex-parser
• Changelog
• 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.