preg_replace_callback

(Auszug aus "Reguläre Ausdrücke" von Jeffrey E. F. Friedl)

preg_replace_callback(pattern, callback, suchstring [, limit [, anzahl ]])

Parameter

pattern

Der Pattern-Parameter: eine Regex mit Begrenzungszeichen, mit optionalen Modifikatoren (siehe Der »Pattern«-Parameter). pattern kann auch ein Array sein, dessen Elemente Pattern-Strings sind.

callback

Eine PHP-Callback-Funktion, die bei jedem erfolgreichen Treffer aufgerufen wird und die den Ersatztext erzeugt.

suchstring

Der Text, der abgesucht werden soll. Auch ein Array von Suchstrings ist zulässig; diese werden der Reihe nach abgearbeitet.

limit

Eine optionale Zahl, die angibt, wie viele Ersetzungen maximal vorgenommen werden sollen (siehe unter Einfaches preg_replace mit je einem Pattern, Ersatztext und Suchstring).

anzahl

Eine optionale Variable, in der die Anzahl der tatsächlich erfolgten Ersetzungen zurückgegeben wird (erst ab PHP 5.1.0, siehe unter Einfaches preg_replace mit je einem Pattern, Ersatztext und Suchstring).

Rückgabewert

Wenn suchstring ein einfacher String ist, ist auch der Rückgabewert ein solcher (eine Kopie des suchstring mit den Ersetzungen). Wenn suchstring ein String-Array ist, wird ebenfalls ein String-Array zurückgegeben (dessen Elemente die modifizierten Versionen der suchstring-Elemente sind).

Erläuterungen

Die Funktion preg_replace_callback ähnelt preg_replace, allerdings ist hier der Ersatztext-Parameter durch eine Callback-Funktion ersetzt. Das Verhalten ist analog zu dem von preg_replace mit dem e-Modifikator (siehe unter Einfaches preg_replace mit je einem Pattern, Ersatztext und Suchstring), aber effizienter (und leichter lesbar, wenn der Ersatztext-Ausdruck kompliziert ist).

Für Einzelheiten zu Callbacks verweise ich Sie auf die PHP-Dokumentation. Kurz gesagt bezieht sich ein PHP-Callback auf eine Funktion, die in vorher festgelegten Situationen mit ebenso vorher festgelegten Argumenten aufgerufen wird. Der Rückgabewert dieser Callback-Funktion wird in der Funktion weiterverarbeitet, die den Callback auslöst. Bei preg_replace_callback wird die Callback-Routine aufgerufen, wenn ein Treffer gefunden wird, und zwar mit genau einem Argument (dem $treffer-Array). Der Rückgabewert der Funktion wird von preg_replace_callback als Ersatztext verwendet.

Das Callback-Argument kann auf verschiedene Arten angegeben werden. Es kann einerseits ein String sein, der den Namen der aufzurufenden Funktion enthält. Es kann auch eine anonyme Funktion sein, die mit der eingebauten PHP-Funktion create_function erzeugt worden ist. Beispiele zu diesen beiden Typen werden wir bald kennenlernen. Es gibt auch einen dritten Typ, der in diesem Buch nicht weiter erwähnt wird, und der für das objektorientierte Programmieren gedacht ist (ein Klassenname und eine Methode daraus).

Hier noch einmal das Programmbeispiel von Einfaches preg_replace mit je einem Pattern, Ersatztext und Suchstring, diesmal mit preg_replace_callback und einer Callback-Funktion. Für den Callback-Parameter wird der Name dieser Funktion als String übergeben.

Wenn dies mit einem $suchstring wie

"R&B" ist "Rhythm and Blues"

aufgerufen wird, erhält man das folgende Ergebnis:

In diesem Programmbeispiel ist text2html_callback eine normale PHP-Funktion, die dafür ausgelegt ist, als Callback von preg_replace_callback aufgerufen zu werden. Dabei wird als einziges Argument das $treffer-Array (das man natürlich auch anders nennen kann, $treffer ist reine Konvention) übergeben.

Der Vollständigkeit halber hier noch eine Version mit einer anonymen Funktion, die mit der eingebauten PHP-Funktion create_function erzeugt wird. Es wird dasselbe $ersatztext-Array wie oben vorausgesetzt. Auch der Inhalt der Callback-Funktion an sich ist identisch, nur wird sie hier nicht mit Namen aufgerufen, sondern der Code wird als anonyme Funktion direkt übergeben und kann nur von preg_replace_callback aufgerufen werden:

Callback oder e-Modifikator?

Bei einfachen Aufgaben ist im Allgemeinen preg_replace mit dem e-Modifikator im Pattern-Argument übersichtlicher als preg_replace_callback. Aus Effizienzgründen kann es aber schon sinnvoll sein, die Callback-Methode zu benutzen. Bei Verwendung des e-Modifikators wird das Ersatztext-Argument bei jedem Treffer erneut als PHP-Code interpretiert. Bei Verwendung von preg_replace_callback fällt dies weg, weil die Callback-Routine nur einmal übersetzt wird.