preg_filter — Funktion · PHP-Referenz

Signatur

Beschreibung

preg_filter() verhält sich wie preg_replace(), mit dem entscheidenden Unterschied: Während preg_replace() alle Elemente zurückgibt (unveränderte inklusive), liefert preg_filter() ausschließlich die Elemente, bei denen tatsächlich ein Treffer aufgetreten ist und damit eine Ersetzung stattgefunden hat. Elemente ohne Treffer werden aus der Rückgabe herausgefiltert.

Wird ein einzelner String als $subject übergeben, ist der Rückgabewert entweder der ersetzte String (wenn ein Treffer gefunden wurde) oder null (wenn kein Treffer vorlag). Wird ein Array übergeben, enthält das Ergebnis-Array nur die Einträge, die mindestens einen Treffer hatten – die Schlüssel bleiben dabei erhalten.

Der Parameter $pattern und $replacement können ebenfalls Arrays sein, wodurch mehrere Muster und Ersetzungen in einem Aufruf angewendet werden können. Ist $pattern ein Array und $replacement ein String, wird dieser String für alle Muster als Ersetzung verwendet.

Der optionale Parameter $count wird auf die Gesamtanzahl der durchgeführten Ersetzungen gesetzt und ermöglicht so eine einfache Erfolgskontrolle.

Parameter

Name	Typ	Default	Beschreibung
$pattern Pflicht	string\|array		Der reguläre Ausdruck als String oder ein Array von regulären Ausdrücken. Muss PCRE-konform sein (inkl. Delimiter, z. B. `/muster/i`).
$replacement Pflicht	string\|array		Der Ersetzungsstring oder ein Array von Ersetzungsstrings. Rückwärtsreferenzen wie `$1` oder `\\1` sind erlaubt.
$subject Pflicht	string\|array		Der zu durchsuchende String oder ein Array von Strings. Bei einem Array werden nur Elemente mit Treffer zurückgegeben.
$limit	int	-1	Maximale Anzahl der Ersetzungen pro Element und Muster. `-1` bedeutet unbegrenzt.
$count	int		Wird nach dem Aufruf auf die Gesamtanzahl der durchgeführten Ersetzungen gesetzt (Referenz-Parameter).

Rückgabewert

Typ

string|array|null

Beschreibung

Wenn $subject ein String ist: Den ersetzten String bei Treffer, null wenn kein Treffer vorlag.

Wenn $subject ein Array ist: Ein Array, das nur die Elemente mit Treffern enthält (mit beibehaltenen Schlüsseln). Tritt ein Fehler auf, wird ebenfalls null zurückgegeben.

Beispiele

Nur passende Array-Elemente zurückgeben

<?php
$eingaben = [
    'alpha',
    'bravo123',
    'charlie',
    'delta456',
    'echo',
];

// Filtere Strings, die Ziffern enthalten, und ersetze die Ziffern
$ergebnis = preg_filter('/\d+/', '[ZAHL]', $eingaben);

print_r($ergebnis);

Array ( [1] => bravo[ZAHL] [3] => delta[ZAHL] )

String-Übergabe: null bei fehlendem Treffer

<?php
$mitTreffer    = preg_filter('/\d+/', '#', 'abc123');
$ohneTreffer   = preg_filter('/\d+/', '#', 'abcdef');

var_dump($mitTreffer);   // string(4) "abc#"
var_dump($ohneTreffer);  // NULL

string(4) "abc#" NULL

Mehrere Muster und Ersetzungen mit $count

<?php
$muster     = ['/foo/', '/bar/', '/baz/'];
$ersetzung  = ['FOO', 'BAR', 'BAZ'];
$texte      = ['foo ist hier', 'nichts passt', 'baz und bar'];

$gefiltert = preg_filter($muster, $ersetzung, $texte, -1, $anzahl);

print_r($gefiltert);
echo "Ersetzungen insgesamt: $anzahl\n";

Array ( [0] => FOO ist hier [2] => BAZ und BAR ) Ersetzungen insgesamt: 3

// Wichtig · Fallstricke

Wichtiger Unterschied zu preg_replace(): preg_replace() gibt bei einem Array immer alle Elemente zurück (unveränderte als Kopie); preg_filter() filtert nicht-treffende Elemente heraus. Das kann zu Verwirrung führen, wenn man unbewusst eines der beiden verwendet.

Bei einem Fehler im regulären Ausdruck (z. B. ungültige Syntax) gibt die Funktion null zurück und löst eine PHP-Warnung aus. Seit PHP 8.0 wird bei PCRE-Fehlern stattdessen eine ValueError-Exception geworfen, wenn das Muster völlig ungültig ist.

Wenn $pattern und $replacement unterschiedlich lange Arrays sind, werden fehlende Ersetzungen durch leere Strings ersetzt – das kann unerwartete Löschungen verursachen.

Siehe auch

preg_replace preg_replace_callback preg_match preg_grep preg_split