Mehrere Textersetzungen in einem einzigen Durchlauf zu erledigen spart Rechenzeit und macht den Code lesbarer. Genau dafür gibt es in PHP die Funktion preg_replace_callback_array(), die eine ganze Liste von Regex-Mustern samt der passenden Callbacks auf einen String anwendet. Dieses Tutorial zeigt die Syntax, den Aufbau der Pattern-Map und drei sofort einsetzbare Beispiele.
Was bringt preg_replace_callback_array gegenüber preg_replace_callback?
Wer in PHP einen Text durch mehrere reguläre Ausdrücke laufen lassen will, kennt den klassischen Weg: Erst preg_replace_callback() mit Pattern A, dann mit Pattern B, dann mit Pattern C. Statt den Text dreimal zu durchsuchen, reicht ein einziger Aufruf. Das funktioniert, führt aber zu Code, der den Subject-String dreimal durchläuft und bei jedem Schritt eine neue Variable speichert. PHP preg_replace_callback_array löst das eleganter, indem es ein Array von Pattern-zu-Callback-Paaren entgegennimmt und alle Ersetzungen in einem Aufruf erledigt.
Bevor es an die Syntax und drei kopierfähige Beispiele geht, ein Blick auf die typischen Anwendungsfälle und die Verfügbarkeit der Funktion.
Die Funktion gibt es seit PHP 7.0 und ist heute in jedem aktuellen PHP-Setup verfügbar. Klassische Anwendungsfälle sind Token-Parser für einfache Templating-Systeme, Markdown-ähnliche Konverter und mehrsprachige Marker-Replacements. In diesem Tutorial geht es um Syntax, Aufbau der Pattern-Map, drei kopierfähige Patterns und einen Performance-Vergleich.
Syntax und Aufbau der Pattern-Map bei PHP preg_replace_callback_array
Die Signatur von PHP preg_replace_callback_array ist auf den ersten Blick lang, im Alltag braucht man aber nur die ersten zwei Parameter.
<?php
preg_replace_callback_array(
array $pattern_callbacks,
string|array $subject,
int $limit = -1,
int &$count = null
): string|array|null
Der erste Parameter ist die Map: ein assoziatives Array, in dem jeder Schlüssel ein Regex-Pattern und jeder Wert ein Callback ist. Die Callbacks können Closures, benannte Funktionen oder beliebige Callables sein. Der zweite Parameter ist der Text (oder ein Array von Texten), auf dem die Patterns angewendet werden. Im Fehlerfall liefert die Funktion null, nicht false.
Wichtig zu verstehen: Jeder Callback bekommt nur die Matches seines eigenen Patterns. Im $matches-Array steht $matches[0] für den Gesamtmatch und $matches[1], $matches[2], ... für die Capture-Groups. Wer schon mit preg_replace_callback gearbeitet hat, erkennt das Schema sofort wieder.
Token-Parser mit PHP preg_replace_callback_array: {{name}}, {{date}} und {{title}}
PHP preg_replace_callback_array glänzt im Templating-Kontext. Ein typischer Anwendungsfall ist ein einfaches Templating. Eine Newsletter-Vorlage enthält Platzhalter wie {{name}} oder {{date}}, die mit konkreten Werten gefüllt werden sollen. Mit preg_replace_callback_array ist das in einem Aufruf erledigt.
<?php
$template = 'Hallo {{name}}, am {{date}} startet {{event}}.';
$daten = ['name' => 'Lina', 'date' => '15.05.2026', 'event' => 'der PHP-Workshop'];
$ergebnis = preg_replace_callback_array(
[
'/\{\{name\}\}/' => fn ($m) => $daten['name'],
'/\{\{date\}\}/' => fn ($m) => $daten['date'],
'/\{\{event\}\}/' => fn ($m) => $daten['event'],
],
$template
);
echo $ergebnis;
/* Hallo Lina, am 15.05.2026 startet der PHP-Workshop. */
Die Pattern-Schlüssel werden escaped, weil { und } in Regex-Syntax Sonderzeichen sind. Die Closures nutzen die kurze Arrow-Function-Syntax fn ($m) => ..., die seit PHP 7.4 verfügbar ist. Wer noch eine ältere Version unterstützen muss, schreibt klassische function ($m) use ($daten) { ... }-Closures.
Mini-Markdown-Replacer mit PHP preg_replace_callback_array
Wer PHP preg_replace_callback_array für einen kleinen Konverter ausprobieren will, hat hier ein passendes Beispiel. Mit drei Patterns lässt sich ein winziger Markdown-ähnlicher Konverter bauen, der **fett**, _kursiv_ und `code` in HTML-Tags umwandelt.
<?php
$text = 'Das ist **wichtig** und _kursiv_, mit `code`.';
$html = preg_replace_callback_array(
[
'/\*\*(.+?)\*\*/' => fn ($m) => '<strong>' . $m[1] . '</strong>',
'/_(.+?)_/' => fn ($m) => '<em>' . $m[1] . '</em>',
'/`(.+?)`/' => fn ($m) => '<code>' . $m[1] . '</code>',
],
$text
);
echo $html;
/* Das ist <strong>wichtig</strong> und <em>kursiv</em>, mit <code>code</code>. */
Das non-greedy .+? sorgt dafür, dass das innerste Paar von Markern matcht, nicht das äußerste. Würde man (.+) ohne Fragezeichen schreiben, würde im Fett-Pattern alles zwischen dem ersten und dem letzten ** als ein einziger Match interpretiert.
Mehrsprachen-Marker und dynamische Map mit PHP preg_replace_callback_array
Beim Arbeiten mit PHP preg_replace_callback_array lassen sich Patterns auch zur Laufzeit zusammenbauen. Bisher war die Map statisch im Code. In einem Mehrsprachen-Setup will man die Marker-Liste aber zur Laufzeit zusammenbauen, weil neue Sprachen ohne Code-Änderung dazukommen sollen.
<?php
$marker = ['de' => 'Hallo', 'en' => 'Hello', 'fr' => 'Bonjour'];
$map = [];
foreach ($marker as $code => $gruss) {
$map['/\{\{' . $code . '\}\}/'] = fn ($m) use ($gruss) => $gruss;
}
$text = '{{de}} | {{en}} | {{fr}}';
echo preg_replace_callback_array($map, $text);
/* Hallo | Hello | Bonjour */
Das Pattern wird als String dynamisch gebaut, der Callback bindet via use den jeweils passenden Wert. Mit dieser Konstruktion lassen sich beliebig viele Marker einbinden, ohne im Aufruf etwas zu ändern. Praktisch ist das auch für Build-Skripte, die env-Templates wie {{DB_HOST}} oder {{API_KEY}} aus einer Konfiguration befüllen.
flowchart TD
A[Input-String] --> B[preg_replace_callback_array]
B --> C[Pattern 1 + Callback 1]
B --> D[Pattern 2 + Callback 2]
B --> E[Pattern N + Callback N]
C --> F[Ergebnis-String]
D --> F
E --> F
Performance-Vergleich von PHP preg_replace_callback_array mit Sequenz
PHP preg_replace_callback_array ist nicht nur kompakter, sondern auch effizienter. Der eigentliche Reiz der Funktion liegt im Performance-Vorteil. Ein klassischer Aufruf mit drei preg_replace_callback durchläuft den String dreimal und legt zwei Zwischenergebnisse als String an.
<?php
$text = 'Pos: 42, Datum: 2026-05-15, User: ID-987';
/* Klassisch: drei Aufrufe */
$step1 = preg_replace_callback('/Pos: (\d+)/', fn ($m) => 'POS=' . $m[1], $text);
$step2 = preg_replace_callback('/Datum: (\d{4}-\d{2}-\d{2})/', fn ($m) => 'DATE=' . $m[1], $step1);
$step3 = preg_replace_callback('/User: ID-(\d+)/', fn ($m) => 'UID=' . $m[1], $step2);
/* Konsolidiert: ein Aufruf */
$kompakt = preg_replace_callback_array([
'/Pos: (\d+)/' => fn ($m) => 'POS=' . $m[1],
'/Datum: (\d{4}-\d{2}-\d{2})/' => fn ($m) => 'DATE=' . $m[1],
'/User: ID-(\d+)/' => fn ($m) => 'UID=' . $m[1],
], $text);
echo $kompakt;
In Benchmarks mit kurzen Texten ist der Unterschied gering. Sobald der Subject mehrere Kilobyte groß wird oder der Aufruf in einer Schleife steckt, wird der konsolidierte Aufruf spürbar schneller, weil PHP intern den Text nur einmal scannt. Ein zweiter Vorteil ist die Lesbarkeit: Alle relevanten Patterns stehen kompakt beieinander, der Leser sieht auf einen Blick, welche Transformationen am Text vorgenommen werden.
Reihenfolge und Stolperfallen
Die Patterns werden in der Reihenfolge des Arrays geprüft. Wer zwei sich überschneidende Patterns hat, sollte das spezifischere zuerst eintragen. Beispiel: Ein Pattern matcht \d+ (jede Zahl), ein anderes matcht \d{4}-\d{2}-\d{2} (ein Datum). Wer das Datum-Pattern erst nach dem allgemeinen Zahlen-Pattern einträgt, riskiert, dass die Jahreszahl als generische Zahl ersetzt wird, bevor das Datum als Ganzes erkannt wird.
Zwei weitere Punkte sind wichtig. Erstens: Das Funktionsergebnis ist null, wenn ein Pattern syntaktisch ungültig ist. Eine kurze Prüfung mit if ($ergebnis === null) schützt vor stillen Fehlern. Zweitens: Bei sehr vielen Patterns (Dutzende oder mehr) auf großen Strings kann die Performance schlechter werden als bei einem einzigen, alles abdeckenden Pattern. Wer Hochleistung braucht, sollte messen, ob die Konsolidierung in eine Multi-Branch-Regex (Alternation) noch schneller ist.
Fazit zu PHP preg_replace_callback_array
preg_replace_callback_array() ist eines der unterschätzten Werkzeuge in PHPs Regex-Familie. PHP preg_replace_callback_array macht Mehrfach-Ersetzungen lesbarer, schneller und konsistenter. Im Token-Parser-Pattern, beim Mini-Markdown-Replacer und bei Mehrsprachen-Markern spielt die Funktion ihre Stärken aus. Wer die Reihenfolge der Patterns bewusst wählt und auf den null-Rückgabewert achtet, baut robuste Templating- und Konverter-Logik in einem einzigen Aufruf.
