mb_ereg_replace_callback — Funktion · PHP-Referenz

Signatur

mb_ereg_replace_callback(string $pattern, callable $callback, string $string, string $options = 'msr'): string|false|null

Beschreibung

mb_ereg_replace_callback() funktioniert ähnlich wie mb_ereg_replace(), übergibt jedoch jeden gefundenen Treffer an eine Callback-Funktion, deren Rückgabewert als Ersetzungstext verwendet wird. Dies ermöglicht dynamische, kontextabhängige Ersetzungen, die mit einem einfachen Ersetzungs-String nicht realisierbar wären – zum Beispiel das Transformieren von Zeichenfolgen, das Formatieren von Zahlen oder das Umschreiben von URLs in Multibyte-Kodierungen wie UTF-8.

Der $pattern-Parameter ist ein POSIX-kompatibler erweiterter regulärer Ausdruck ohne Begrenzer (Delimiter). Die Callback-Funktion erhält als ersten Parameter ein Array mit dem vollständigen Treffer (Index 0) sowie allen Gruppen-Treffern (ab Index 1), analog zu preg_replace_callback(). Der Rückgabewert des Callbacks wird in den Ergebnis-String eingesetzt.

Über den $options-Parameter lässt sich das Verhalten steuern: i für Groß-/Kleinschreibungsignoranz, x für den erweiterten Modus (Leerzeichen im Muster ignorieren), m für den Mehrzeilenmodus, s damit . auch Zeilenumbrüche matcht, r für Rückwärtskompabilität sowie z für den End-of-String-Modus.

Diese Funktion ist besonders nützlich, wenn Multibyte-Zeichenkodierungen (z. B. UTF-8, Shift-JIS) korrekt verarbeitet werden müssen und gleichzeitig eine flexible, programmgesteuerte Ersetzungslogik benötigt wird.

Parameter

Name	Typ	Default	Beschreibung
$pattern Pflicht	string		Der reguläre Ausdruck im POSIX-erweiterten Format ohne Begrenzerzeichen. Multibyte-Zeichen werden korrekt berücksichtigt.
$callback Pflicht	callable		Eine aufrufbare Funktion, die für jeden Treffer aufgerufen wird. Sie erhält ein Array mit dem vollständigen Treffer (Index `0`) und optionalen Gruppen-Treffern. Der Rückgabewert des Callbacks dient als Ersetzungstext.
$string Pflicht	string		Die zu durchsuchende Zeichenkette. Wird entsprechend der internen Multibyte-Zeichenkodierung (`mb_internal_encoding()`) behandelt.
$options	string	msr	Optionszeichen als String. Mögliche Werte: `i` (Groß-/Kleinschreibung ignorieren), `x` (erweiterter Modus), `m` (Mehrzeilenmodus), `s` (`.` matcht auch Zeilenumbrüche), `r` (POSIX-Kompatibilität), `z` (End-of-String-Modus).

Rückgabewert

Typ

string|false|null

Beschreibung

Gibt den veränderten String zurück, wenn Treffer gefunden und ersetzt wurden. Gibt den Originalstring zurück, wenn keine Treffer gefunden wurden. Gibt false zurück, wenn ein Fehler aufgetreten ist. Gibt null zurück, wenn das Encoding ungültig ist (ab PHP 8.0).

Beispiele

Wörter in einem UTF-8-String in Großbuchstaben umwandeln

<?php
mb_internal_encoding('UTF-8');

$text = 'héllo wörld, wie geht es dir?';

$result = mb_ereg_replace_callback(
    '[[:alpha:]]+',
    function (array $matches): string {
        return mb_strtoupper($matches[0], 'UTF-8');
    },
    $text
);

echo $result;

HÉLLO WÖRLD, WIE GEHT ES DIR?

Zahlen im String verdoppeln (auch Multibyte-Kontext)

<?php
mb_internal_encoding('UTF-8');

$text = 'Ich habe 3 Äpfel und 12 Birnen gekauft.';

$result = mb_ereg_replace_callback(
    '[0-9]+',
    function (array $matches): string {
        return (string)((int)$matches[0] * 2);
    },
    $text
);

echo $result;

Ich habe 6 Äpfel und 24 Birnen gekauft.

Erfassen von Gruppen zur URL-Umschreibung

<?php
mb_internal_encoding('UTF-8');

$html = 'Besuche <a href="http://example.com/seite">unsere Seite</a> oder <a href="http://example.com/kontakt">Kontakt</a>.';

$result = mb_ereg_replace_callback(
    'href="http://example\.com/([^"]+)"',
    function (array $matches): string {
        return 'href="https://neu.example.com/' . $matches[1] . '"';
    },
    $html
);

echo $result;

Besuche <a href="https://neu.example.com/seite">unsere Seite</a> oder <a href="https://neu.example.com/kontakt">Kontakt</a>.

// Wichtig · Fallstricke

Encoding-Abhängigkeit: Die Funktion arbeitet mit der aktuell gesetzten internen Multibyte-Kodierung (mb_internal_encoding()). Stellen Sie sicher, dass die Kodierung korrekt gesetzt ist, bevor Sie mb_ereg_replace_callback() aufrufen, um unerwartete Ergebnisse zu vermeiden.

Kein Delimiter: Anders als bei preg_replace_callback() wird der reguläre Ausdruck ohne Begrenzerzeichen (z. B. /) angegeben. Das Hinzufügen eines Delimiters führt zu einem fehlerhaften Muster.

Sicherheit: Wenn der $pattern aus Benutzereingaben stammt, muss er sorgfältig validiert oder maskiert werden, da unkontrollierte reguläre Ausdrücke zu ReDoS-Angriffen (Regular Expression Denial of Service) führen können.

Alternative: In den meisten Fällen ist preg_replace_callback() mit dem u-Modifier (Unicode) eine modernere und flexiblere Alternative, da PCRE-Ausdrücke mächtiger und besser dokumentiert sind als POSIX-Ausdrücke.

Siehe auch

mb_ereg_replace mb_ereg preg_replace_callback mb_internal_encoding mb_strtoupper