preg_replace_callback_array

Einführung

In PHP sind reguläre Ausdrücke ein unverzichtbares Werkzeug zum Abgleichen, Suchen und Transformieren von Zeichenketten. Die seit PHP 7.1 verfügbare Funktion preg_replace_callback_array() ermöglicht es, alle Treffer mehrerer regulärer Ausdrucksmuster in einem einzigen Aufruf zu ersetzen, wobei jedes Muster seinen eigenen Callback hat, der den Ersatz berechnet. Sie ist das array-basierte Pendant zu preg_replace_callback(): Anstatt ein Muster und einen Callback zu übergeben, übergeben Sie eine Zuordnung von pattern => callback-Paaren.

Dieses Kapitel erklärt, was die Funktion zurückgibt, beschreibt ihre Parameter und zeigt ausführbare Beispiele – einschließlich häufiger Fallstricke rund um die Reihenfolge der Muster und Rückgabetypen.

Wann sollte sie verwendet werden?

Greifen Sie auf preg_replace_callback_array() zurück, wenn:

• Sie unterschiedliche Ersetzungslogik auf verschiedene Muster in einem einzigen Durchlauf über den Eingabetext anwenden müssen.
• Sie andernfalls mehrere preg_replace_callback()-Aufrufe verketten würden – deren Zusammenfassung macht den Code lesbarer und hält die Absicht an einem Ort.
• Der Ersatzwert nicht als statische Zeichenkette ausgedrückt werden kann, sodass preg_replace() nicht ausreicht – Sie müssen ihn aus dem gefundenen Text berechnen.

Wenn Sie nur ein einziges Muster haben, verwenden Sie preg_replace_callback(). Wenn die Ersetzungen feste Zeichenketten sind, verwenden Sie preg_replace().

Syntax

preg_replace_callback_array(
    array $pattern_and_callbacks,
    string|array $subject,
    int $limit = -1,
    int &$count = null,
    int $flags = 0
): string|array|null

Rückgabewert: Wenn $subject eine Zeichenkette ist, wird eine Zeichenkette zurückgegeben; wenn $subject ein Array ist, wird ein Array zurückgegeben. Bei einem Regex-Fehler wird null zurückgegeben.

Hinweis: Callbacks sollten eine Zeichenkette zurückgeben. Ein numerischer Rückgabewert (wie ein int) wird automatisch in eine Zeichenkette umgewandelt. Die Rückgabe von null ergibt eine leere Zeichenkette.

Grundlegendes Beispiel

Der erste Callback schreibt jedes Wort in Großbuchstaben; der zweite erhöht jede Folge von Ziffern um eins. Beide Muster werden in einem einzigen Aufruf auf denselben Eingabetext angewendet.

<?php

$patterns_and_callbacks = [
  '/[a-z]+/i' => function ($matches) {
    return strtoupper($matches[0]);
  },
  '/\d+/' => function ($matches) {
    return (int) $matches[0] + 1;
  },
];

$string = 'This is a test string with 1234';

echo preg_replace_callback_array($patterns_and_callbacks, $string);
// THIS IS A TEST STRING WITH 1235

Hier ist $matches[0] der vollständige Text, der vom Muster gefunden wurde. Der zweite Callback gibt eine ganze Zahl zurück (1234 + 1), die PHP in die Zeichenkette "1235" umwandelt.

Die Reihenfolge der Muster ist wichtig

Die Muster werden in der Reihenfolge des Arrays angewendet, und jedes läuft auf dem Ergebnis des vorherigen. Das bedeutet, dass ein früherer Callback den Text verändern kann, den ein späteres Muster sieht – eine häufige Quelle von Überraschungen.

<?php

$subject = 'abc123';

$result = preg_replace_callback_array([
  // Runs first: wraps every digit run in brackets.
  '/\d+/' => fn ($m) => '[' . $m[0] . ']',
  // Runs second: now sees "abc[123]" and upper-cases the letters.
  '/[a-z]+/' => fn ($m) => strtoupper($m[0]),
], $subject);

echo $result;
// ABC[123]

Wenn Sie die beiden Muster in umgekehrter Reihenfolge anordneten, würden die Buchstaben zuerst in Großbuchstaben umgewandelt, bevor das Ziffernmuster läuft – das Ziffernergebnis bleibt gleich, aber im Allgemeinen kann die Reihenfolge die Ausgabe verändern.

Ersetzungen zählen mit $count

Übergeben Sie eine Variable als viertes Argument, um zu erfahren, wie viele Ersetzungen über alle Muster hinweg vorgenommen wurden.

<?php

$subject = 'cat dog cat bird cat';

$result = preg_replace_callback_array(
  ['/cat/' => fn ($m) => 'fish'],
  $subject,
  -1,
  $count
);

echo $result . "\n"; // fish dog fish bird fish
echo "Replacements: $count"; // Replacements: 3

Mit einem Array als Eingabe arbeiten

Wenn $subject ein Array ist, verarbeitet die Funktion jedes Element und gibt ein Array derselben Form zurück.

<?php

$subjects = ['Order #12', 'Order #7'];

$result = preg_replace_callback_array(
  ['/\d+/' => fn ($m) => str_pad($m[0], 4, '0', STR_PAD_LEFT)],
  $subjects
);

print_r($result);
// Array
// (
//     [0] => Order #0012
//     [1] => Order #0007
// )

Häufige Fallstricke

• Trennzeichen vergessen. Schlüssel müssen gültige Regex-Zeichenketten mit Trennzeichen sein, z. B. '/\d+/', nicht '\d+'. Ein fehlendes Trennzeichen lässt den Aufruf null zurückgeben und eine Warnung ausgeben.
• Absichtlich Nicht-Zeichenketten zurückgeben. Während numerische Rückgaben automatisch umgewandelt werden, löst die Rückgabe von Arrays oder Objekten einen TypeError aus. Wandeln Sie Ihren Wert vor der Rückgabe um oder formatieren Sie ihn.
• Annehmen, dass Muster unabhängig sind. Wie oben gezeigt, arbeitet jedes Muster auf der Ausgabe des vorherigen. Ordnen Sie Ihre Zuordnung bewusst an.
• Capture-Gruppen vs. den vollständigen Treffer verwechseln. $matches[0] ist der gesamte Treffer; $matches[1], $matches[2], … sind die erfassten Gruppen. Referenzieren Sie den richtigen Index für Ihre Logik.

Verwandte Funktionen

• preg_replace_callback() — ein Muster + ein Callback.
• preg_replace() — Ersetzen mit statischen Zeichenketten oder Rückverweisen.
• preg_match() und preg_match_all() — Treffer finden ohne Ersetzen.
• PHP-Callback-Funktionen — wie Callables in PHP funktionieren.

Fazit

preg_replace_callback_array() bietet eine saubere, einpass-basierte Möglichkeit, unterschiedliche Ersetzungslogik auf mehrere Regex-Muster anzuwenden. Sie glänzt besonders, wenn jedes Muster seinen eigenen berechneten Ersatz benötigt, und ersetzt dabei, was sonst mehrere verkettete preg_replace_callback()-Aufrufe wären. Denken Sie daran, dass Muster in der Array-Reihenfolge ausgeführt werden und dass Callbacks Zeichenketten zurückgeben sollten, und die Funktion hält Ihren Text-Transformations-Code kompakt und lesbar.

Übung