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 inext/strmatch(may move toext/standard\Str) - Discussion thread: php.internals/133028
- Voting: Not yet initiated; provisional question asks for 2/3 majority on accepting
Str\Matcher,Str\Replacer, andStr\MatchResultas 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.