preg_grep — Funktion · PHP-Referenz

Signatur

preg_grep(string $pattern, array $array, int $flags = 0): array|false

Beschreibung

preg_grep() wendet einen regulären Ausdruck auf jedes Element eines Arrays an und gibt ein neues Array zurück, das nur die Elemente enthält, die auf das Muster passen. Die ursprünglichen Schlüssel des Arrays bleiben dabei erhalten.

Besonders nützlich ist die Funktion, wenn man aus einer Liste von Werten nur diejenigen filtern möchte, die einem bestimmten Format entsprechen – etwa alle numerischen Werte, E-Mail-Adressen oder Zeichenketten mit einem bestimmten Präfix. Gegenüber einer manuellen foreach-Schleife mit preg_match() ist preg_grep() kompakter und gut lesbar.

Über den optionalen Parameter $flags lässt sich das Verhalten umkehren: Mit der Konstante PREG_GREP_INVERT werden stattdessen alle Elemente zurückgegeben, die nicht auf das Muster passen – also die Inverse der normalen Filterung.

Im Fehlerfall (z. B. bei ungültigem regulären Ausdruck) gibt die Funktion false zurück. Nicht-skalare Array-Werte (z. B. Arrays oder Objekte) werden intern als leere Zeichenkette behandelt und passen daher nur auf Muster, die auch auf leere Strings passen.

Parameter

Name	Typ	Default	Beschreibung
$pattern Pflicht	string		Der reguläre Ausdruck als Zeichenkette inklusive Begrenzer (Delimiter), z. B. `'/^\d+$/'`.
$array Pflicht	array		Das zu durchsuchende Eingangs-Array. Die Schlüssel werden im Ergebnis-Array beibehalten.
$flags	int	0	Optionales Bitfeld. Wird `PREG_GREP_INVERT` übergeben, werden nur Elemente zurückgegeben, die nicht auf das Muster passen.

Rückgabewert

Typ

array|false

Beschreibung

Gibt ein Array mit den passenden Elementen (oder bei PREG_GREP_INVERT den nicht-passenden Elementen) zurück. Die ursprünglichen Schlüssel bleiben erhalten. Bei einem Fehler (z. B. ungültiger regulärer Ausdruck) wird false zurückgegeben.

Beispiele

Nur numerische Werte aus einem gemischten Array filtern

<?php
$werte = ['alpha', '42', '3.14', 'beta', '0', 'gamma', '100'];

// Nur Elemente, die rein aus Ziffern bestehen
$zahlen = preg_grep('/^\d+$/', $werte);

print_r($zahlen);

Array ( [1] => 42 [4] => 0 [6] => 100 )

Invertierte Filterung mit PREG_GREP_INVERT

<?php
$werte = ['alpha', '42', '3.14', 'beta', '0', 'gamma', '100'];

// Alle Elemente, die KEINE reinen Ganzzahlen sind
$keine_ganzzahlen = preg_grep('/^\d+$/', $werte, PREG_GREP_INVERT);

print_r($keine_ganzzahlen);

Array ( [0] => alpha [2] => 3.14 [3] => beta [5] => gamma )

E-Mail-Adressen aus einem Array herausfiltern

<?php
$eingaben = [
    'kein-email',
    'nutzer@beispiel.de',
    'auch-kein-email',
    'admin@example.com',
    'falsch@',
];

$emails = preg_grep('/^[^@\s]+@[^@\s]+\.[^@\s]+$/', $eingaben);

foreach ($emails as $key => $email) {
    echo "[$key] $email\n";
}

[1] nutzer@beispiel.de [3] admin@example.com

// Wichtig · Fallstricke

Schlüsseln-Erhalt: Da preg_grep() die originalen Array-Schlüssel beibehält, kann das Ergebnis-Array Lücken in den numerischen Indizes aufweisen. Soll ein dicht gepacktes Array ohne Lücken entstehen, muss array_values() nachgelagert aufgerufen werden.

Nicht-skalare Werte: Enthält das Array Elemente vom Typ array, object oder null, werden diese intern zu einem leeren String konvertiert. Das kann zu unerwarteten Treffern führen, wenn das Muster auch auf leere Strings passt.

Fehlerbehandlung: Bei einem ungültigen regulären Ausdruck gibt die Funktion false zurück und erzeugt einen PHP-Fehler (E_WARNING). Der Rückgabewert sollte daher mit === false geprüft werden.

Siehe auch

preg_match preg_match_all preg_replace array_filter array_values