Die Funktion preg_replace_callback() gehört zu den leistungsfähigsten Werkzeugen für Textverarbeitung in PHP. Während preg_replace() nur statische Ersetzungen oder einfache Rückreferenzen erlaubt, ermöglicht preg_replace_callback() die vollständige Kontrolle über jeden einzelnen Treffer. Eine Callback-Funktion empfängt den gefundenen Treffer als Array und gibt den Ersetzungsstring dynamisch zurück. Damit lassen sich Aufgaben wie Formatkonvertierungen, bedingte Ersetzungen oder kontextabhängige Transformationen elegant lösen. Dieses Tutorial erklärt die Syntax, zeigt praktische Beispiele und beleuchtet die Unterschiede zu verwandten Funktionen.
Doch wann genau wird eine Callback-Funktion für Ersetzungen benötigt und wo liegen die Grenzen von preg_replace()?
Warum preg_replace_callback?
Reguläre Ausdrücke finden Muster in Texten. Für einfache Ersetzungen reicht preg_replace() aus, doch sobald die Ersetzung von der Logik abhängt, stößt diese Funktion an ihre Grenzen. Vor PHP 7.0 gab es den /e-Modifier, der den Ersetzungsstring als PHP-Code auswertete. Dieser Modifier wurde wegen schwerwiegender Sicherheitsrisiken entfernt. Die Funktion preg_replace_callback() ist der sichere und flexible Ersatz dafür. Sie trennt das Suchmuster sauber von der Verarbeitungslogik und erlaubt beliebig komplexe Berechnungen innerhalb der Callback-Funktion.
Syntax und Parameter
Die Funktion erwartet mindestens drei Parameter und gibt den veränderten String oder ein Array zurück. Jeder Parameter erfüllt eine klar definierte Aufgabe.
<?php
$ergebnis = preg_replace_callback(
string|array $pattern,
callable $callback,
string|array $subject,
int $limit = -1,
int &$count = null,
int $flags = 0
);
Pattern (Suchmuster)
Das Pattern ist ein regulärer Ausdruck im PCRE-Format. Es wird in Trennzeichen eingeschlossen, üblicherweise Schrägstriche. Gruppen in runden Klammern erzeugen Untergruppen, die im Matches-Array verfügbar sind. Auch ein Array aus mehreren Patterns kann übergeben werden.
Callback-Funktion
Die Callback-Funktion wird für jeden Treffer aufgerufen. Sie empfängt ein Array mit dem vollständigen Treffer an Index 0 und allen eingefangenen Gruppen an den folgenden Indizes. Die Funktion muss zwingend einen String zurückgeben, der den Treffer im Ergebnis ersetzt.
Subject (Eingabestring)
Der Subject-Parameter enthält den zu durchsuchenden Text. Wird ein Array von Strings übergeben, wendet PHP die Ersetzung auf jedes Element an und gibt ein Array zurück.
Limit und Count
Der optionale Limit-Parameter begrenzt die Anzahl der Ersetzungen pro Subject-String. Der Standardwert -1 bedeutet unbegrenzt. Der Count-Parameter wird per Referenz übergeben und enthält nach dem Aufruf die Gesamtzahl der durchgeführten Ersetzungen.
Anonyme Funktionen als Callback
Anonyme Funktionen (Closures) sind die bevorzugte Form für Callbacks in preg_replace_callback(). Sie halten die Ersetzungslogik direkt am Ort des Aufrufs und machen den Code lesbarer. Mit dem use-Keyword lassen sich externe Variablen in die Closure einbinden.
<?php
$waehrung = 'EUR';
$text = 'Der Preis betraegt 49.90 oder 99.50 brutto.';
$ergebnis = preg_replace_callback(
'/(\d+\.\d{2})/',
function (array $matches) use ($waehrung): string {
$betrag = number_format((float) $matches[1], 2, ',', '.');
return $betrag . ' ' . $waehrung;
},
$text
);
echo $ergebnis;
/* Ausgabe: Der Preis betraegt 49,90 EUR oder 99,50 EUR brutto. */
Die Closure greift über use ($waehrung) auf die externe Variable zu und formatiert jeden gefundenen Geldbetrag mit deutschem Zahlenformat und Währungsangabe.
Das Matches-Array im Callback
Das Matches-Array ist das zentrale Element jeder Callback-Funktion. An Index 0 steht immer der gesamte Treffer. Jede eingefangene Gruppe erhält einen aufsteigenden numerischen Index. Benannte Gruppen sind zusätzlich über ihren Namen erreichbar.
<?php
$datum = 'Heute ist der 06.03.2026 und morgen der 07.03.2026.';
$ergebnis = preg_replace_callback(
'/(?P<tag>\d{2})\.(?P<monat>\d{2})\.(?P<jahr>\d{4})/',
function (array $matches): string {
return $matches['jahr'] . '-' . $matches['monat'] . '-' . $matches['tag'];
},
$datum
);
echo $ergebnis;
/* Ausgabe: Heute ist der 2026-03-06 und morgen der 2026-03-07. */
Durch benannte Gruppen wie (?P<tag>...) wird der Code innerhalb der Callback-Funktion deutlich verständlicher als bei rein numerischen Indizes.
flowchart TD
A["Subject-String"] --> B["Pattern anwenden"]
B --> C["Treffer gefunden"]
C --> D["Callback aufrufen mit matches-Array"]
D --> E["return String aus Callback"]
E --> F["Ersetzung einfügen"]
F --> G{"Weitere Treffer?"}
G -->|Ja| C
G -->|Nein| H["Ergebnis-String"]
Praktische Beispiele
Die folgenden Beispiele zeigen typische Einsatzgebiete von preg_replace_callback() in der Praxis. Ein häufiger Anwendungsfall ist die Umwandlung von Platzhaltern in einem Template-System.
<?php
$vorlage = 'Hallo {{name}}, deine Bestellung {{bestellnr}} ist bereit.';
$daten = [
'name' => 'Max Mustermann',
'bestellnr' => 'B-2026-0042',
];
$ergebnis = preg_replace_callback(
'/\{\{(\w+)\}\}/',
function (array $matches) use ($daten): string {
$schluessel = $matches[1];
return $daten[$schluessel] ?? $matches[0];
},
$vorlage
);
echo $ergebnis;
/* Ausgabe: Hallo Max Mustermann, deine Bestellung B-2026-0042 ist bereit. */
Die Callback-Funktion schaut im Daten-Array nach dem Platzhalternamen und gibt den Originaltext zurück, falls kein passender Wert existiert.
preg_replace_callback_array()
Seit PHP 7.0 gibt es preg_replace_callback_array(). Diese Funktion erlaubt es, verschiedene Patterns mit jeweils eigenen Callback-Funktionen zu kombinieren. Statt eines einzelnen Patterns wird ein assoziatives Array übergeben, bei dem die Schlüssel die Patterns und die Werte die zugehörigen Callbacks sind.
<?php
$text = 'Temperatur: 100F, Laenge: 10in';
$ergebnis = preg_replace_callback_array(
[
'/(\d+)F/' => function (array $matches): string {
$celsius = round(($matches[1] - 32) * 5 / 9);
return $celsius . '°C';
},
'/(\d+)in/' => function (array $matches): string {
$cm = round($matches[1] * 2.54, 1);
return $cm . 'cm';
},
],
$text
);
echo $ergebnis;
/* Ausgabe: Temperatur: 38°C, Laenge: 25.4cm */
Jedes Pattern wird mit seinem eigenen Callback verarbeitet. Das macht den Code übersichtlicher als verschachtelte Aufrufe von preg_replace_callback() und vermeidet unnötige Zwischenvariablen.
preg_replace vs. preg_replace_callback
Die Wahl zwischen beiden Funktionen hängt vom Anwendungsfall ab. Für einfache statische Ersetzungen oder Rückreferenzen wie $1 genügt preg_replace(). Sobald die Ersetzung eine Berechnung, eine Bedingung oder einen Funktionsaufruf erfordert, ist preg_replace_callback() die richtige Wahl. Der frühere /e-Modifier für preg_replace(), der PHP-Code im Ersetzungsstring ausführte, wurde in PHP 7.0 entfernt. Er stellte ein erhebliches Sicherheitsrisiko dar, weil beliebiger Code ausgeführt werden konnte. Bestehender Code mit dem /e-Modifier muss auf preg_replace_callback() umgestellt werden. Die Callback-Variante ist nicht nur sicherer, sondern auch lesbarer und besser debuggbar, da die Logik in einer echten Funktion statt in einem String steckt.
Fehlerbehandlung und Best Practices
Robuster Code prüft den Rückgabewert von preg_replace_callback(). Bei einem fehlerhaften Pattern gibt die Funktion null zurück. Mit preg_last_error() lässt sich der genaue Fehlercode ermitteln. Seit PHP 8.0 wirft die Funktion zusätzlich eine ValueError, wenn das Pattern ungültig ist.
Die Callback-Funktion muss immer einen String zurückgeben. Fehlt das return-Statement, verwendet PHP null, was zu einer impliziten Konvertierung in einen leeren String führt und Teile des Textes stillschweigend entfernt. Für die Performance gilt: Wenn dasselbe Pattern häufig verwendet wird, sollte es in einer Variablen gespeichert werden. Bei sehr großen Texten kann der Limit-Parameter helfen, die Verarbeitung zu steuern. Benannte Gruppen erhöhen die Lesbarkeit und verringern die Fehleranfälligkeit bei komplexen Patterns. Reguläre Ausdrücke sollten so einfach wie möglich gehalten werden, da komplexe Patterns die Wartung erschweren und die Performance verschlechtern können.
Fazit
Die Funktion preg_replace_callback() ist der sichere und flexible Weg für dynamische Textersetzungen in PHP. Sie ersetzt den unsicheren /e-Modifier vollständig und bietet durch den Einsatz von Closures eine saubere Trennung von Suchmuster und Verarbeitungslogik. Das Matches-Array liefert den vollständigen Treffer samt aller Gruppen, während die Callback-Funktion beliebige Transformationen durchführen kann. Mit preg_replace_callback_array() lassen sich mehrere Patterns mit unterschiedlichen Callbacks in einem einzigen Aufruf kombinieren. Wer reguläre Ausdrücke in PHP einsetzt, sollte preg_replace_callback() als Standardwerkzeug für alle Fälle kennen, in denen statische Ersetzungen nicht ausreichen.
