Ehsan Bagherzadegan
Back to articles
6 min read

PHP RFC: Prepared Literal String Matching with Str\Matcher and Str\Replacer

A new PHP RFC proposes Str\Matcher and Str\Replacer — reusable, Aho–Corasick-based classes for efficient multi-pattern string matching and replacement, targeting high-volume filtering and content processing workloads.

PHP has long had a gap in its standard library: no reusable, prepared object for multi-pattern literal string matching. You could use strtr() for replacement, but its internal structure isn't exposed. You could loop str_contains() or preg_match(), but that repeats work when the same dictionary is applied to many inputs.

A new RFC proposed on November 6, 2026 aims to close that gap. Prepared Literal String Matching and Replacement introduces Str\Matcher and Str\Replacer — immutable, reusable objects built on the Aho–Corasick algorithm. They target workloads where a large, rarely changing dictionary is matched against many texts: log filtering, content moderation, keyword extraction, PII redaction, and similar tasks.

The RFC is currently under discussion (v0.3) with implementation in PR #25122. If accepted, it would likely target PHP 8.7 or later.

The Problem Space

Consider a content moderation system that checks user input against a list of 500 prohibited terms. Today you have a few options, each with drawbacks:

// Option 1: Loop str_contains — O(n * m) per input
foreach ($prohibited as $term) {
    if (str_contains($input, $term)) { /* ... */ }
}

// Option 2: Single regex alternation — complex, hard to maintain
$pattern = '/' . implode('|', array_map('preg_quote', $prohibited)) . '/i';
preg_match($pattern, $input);

// Option 3: strtr for replacement only — no match enumeration, no reuse
strtr($input, $replacements);

None of these let you prepare the dictionary once and reuse it efficiently across requests. strtr() does build an internal trie, but you can't inspect matches, count overlaps, or enumerate positions.

The Proposed API

Str\Matcher — Finding Matches

final class Matcher {
    public function __construct(array $keywords) {}
    public function matches(string $subject): bool {}
    public function countMatches(string $subject): int {}
    /** @return list<string> */
    public function getMatchedKeywords(string $subject): array {}
    /** @return list<MatchResult> */
    public function matchAll(string $subject): array {}
    /** @return list<string> */
    public function getKeywords(): array {}
}

final class MatchResult {
    public readonly int $offset;
    public readonly int $length;
    public readonly string $keyword;
}

Matching semantics: case-sensitive, byte-oriented, non-regex. matches() stops at the first detected match end (fast boolean check). countMatches() includes overlapping occurrences. getMatchedKeywords() returns each keyword once, ordered by first occurrence. matchAll() returns all occurrences ordered by start offset, then by length (longest first at each position).

Str\Replacer — Replacing Matches

final class Replacer {
    public function __construct(array $replacements) {}
    public function replace(string $subject, &$count = null): string {}
    public function getReplacements(): array {}
}

Replacement semantics: non-overlapping, leftmost-longest selection (matching strtr() behavior). Replacement text is not reprocessed. The optional $count reference receives the number of replacements made.

Practical Examples

Overlapping Match Enumeration

One of Matcher's strengths is handling overlaps correctly — something strtr() and regex alternation handle differently or not at all.

$matcher = new Str\Matcher(['a', 'aa']);

// Counts all overlapping occurrences
$matcher->countMatches('aaa'); // 5

// Enumerates each occurrence with byte offsets
$matcher->matchAll('aaa');
/*
[
    MatchResult { offset: 0, length: 1, keyword: 'a' },
    MatchResult { offset: 0, length: 2, keyword: 'aa' },
    MatchResult { offset: 1, length: 1, keyword: 'a' },
    MatchResult { offset: 1, length: 2, keyword: 'aa' },
    MatchResult { offset: 2, length: 1, keyword: 'a' },
]
*/

Longest-Match Replacement

Replacer applies the leftmost-longest rule, so longer keys take precedence at each position without rescanning inserted text.

$replacer = new Str\Replacer([
    'a'  => 'Y',
    'aa' => 'X',
]);

$replacer->replace('aaa', $count);
// Result: 'XY'
// $count = 2
// Explanation: position 0 matches 'aa' → 'X', position 2 matches 'a' → 'Y'

This mirrors strtr() behavior but with a prepared, reusable object.

Content Moderation: Prepared Once, Used Many Times

// Build once at startup (e.g., from config/database)
$prohibitedTerms = [
    'spam', 'scam', 'phishing', 'malware', 'ransomware',
    // ... hundreds more
];

$matcher = new Str\Matcher($prohibitedTerms);
$replacer = new Str\Replacer(array_combine($prohibitedTerms, array_fill(0, count($prohibitedTerms), '[REDACTED]')));

// Reuse per request — no rebuild cost
function moderate(string $input, Str\Matcher $matcher, Str\Replacer $replacer): array {
    if (!$matcher->matches($input)) {
        return ['clean' => true, 'text' => $input];
    }

    $matches = $matcher->getMatchedKeywords($input);
    $cleaned = $replacer->replace($input, $count);

    return [
        'clean' => false,
        'flagged' => $matches,
        'replacements' => $count,
        'text' => $cleaned,
    ];
}

Keyword Extraction for SEO/Analytics

$keywords = [
    'laravel', 'php', 'symfony', 'doctrine', 'filament',
    'livewire', 'inertia', 'pest', 'phpstan', 'rector',
];

$matcher = new Str\Matcher($keywords);

function extractTopics(string $content, Str\Matcher $matcher): array {
    $found = $matcher->getMatchedKeywords($content);
    $counts = [];

    foreach ($matcher->matchAll($content) as $match) {
        $counts[$match->keyword] = ($counts[$match->keyword] ?? 0) + 1;
    }

    arsort($counts);
    return $counts;
}

PII Redaction with Position Information

$patterns = [
    'email' => '/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/',
    // Note: Matcher is literal-only. For regex patterns, you'd still use preg_replace_callback.
    // But for fixed PII tokens (API keys, known ID formats), Matcher works:
    'api_key_' => 'API_KEY_REDACTED',
    'bearer_'  => 'TOKEN_REDACTED',
];

$replacer = new Str\Replacer($patterns);

$logLine = 'User api_key_abc123 authenticated with bearer_xyz789';
$replacer->replace($logLine);
// 'User API_KEY_REDACTED authenticated with TOKEN_REDACTED'

Performance Characteristics

The RFC benchmarks show where the prepared approach shines and where it doesn't.

Scenario Best Existing One-shot (vs best) Prepared reuse
getMatchedKeywords(); 4 KiB, 128 keys preg_match_all() -43% Faster
matches(); 4 KiB, 128 keys, no match preg_match() -42% Faster
replace(); 16 KiB, 32 keys preg_replace_callback() -36% Faster
replace(); 1 MiB, 10K keys, no replace strtr() +363% (mixed) / -64% (equal) Faster

Key takeaway: the one-shot cost (construction + call) pays off around 16 KiB for ~32 keys, or ~64 calls for 128-byte texts. In long-running processes (Swoole, FrankenPHP, RoadRunner) where the object lives across requests, the prepared reuse is faster in all tested cases.

For small inputs or single-use scripts, strtr(), str_contains(), or a simple regex will still be simpler and often faster.

When to Use This (and When Not To)

Good fits:

  • Large dictionaries (hundreds to thousands of keywords) applied to many inputs
  • Long-running PHP processes where the prepared object persists across requests
  • Need for overlap enumeration, position data, or unique keyword lists
  • Binary-safe, case-sensitive literal matching

Stick with existing tools when:

  • Dictionary is tiny (< 10 keys) or single-use
  • You need case-insensitive or Unicode-aware matching (out of scope for v1)
  • You need regex patterns (Matcher is literal-only)
  • One-off scripts where construction overhead isn't amortized

Current Status and Outlook

  • RFC: Under discussion (v0.3, 2026-11-06) at wiki.php.net/rfc/prepared_literal_string_matching
  • Implementation: PR #25122 targeting php:master, currently in ext/strmatch (may move to ext/standard\Str)
  • Discussion thread: php.internals/133028
  • Voting: Not yet initiated; provisional question asks for 2/3 majority on accepting Str\Matcher, Str\Replacer, and Str\MatchResult as a single package

Main feedback so far (Larry Garfield) questions whether this is too niche for the stdlib and requests more practical comparisons vs. strtr() and str_contains(). The author has noted that case-insensitive matching, Unicode normalization, callbacks, streaming, serialization, and persistent caching are explicitly out of scope for this RFC.

Takeaway

If this RFC passes, PHP gains a standard-library primitive for a class of string problems that currently require userland implementations or external extensions. For applications doing high-volume keyword filtering, content classification, or log processing — especially on long-running PHP servers — Str\Matcher and Str\Replacer will offer a clean, performant, and dependency-free solution.

Keep an eye on the internals thread if you have opinions on the API shape (e.g., matchAll() return type, inout $count in replace(), object equality semantics). The vote hasn't started yet, and feedback at this stage can still influence the final design.

Sources