preg_match
(PHP 4, PHP 5, PHP 7, PHP 8)
preg_match — Führt eine Suche mit einem regulären Ausdruck durch
Beschreibung
string
$pattern
,string
$subject
,array
&$matches
= null
,int
$flags
= 0,int
$offset
= 0): int|false
Durchsucht subject
nach Übereinstimmungen mit dem in
pattern
angegebenen regulären Ausdruck.
Parameter-Liste
-
pattern
-
Der Ausdruck, nach dem gesucht werden soll, als Zeichenkette.
-
subject
-
Die zu durchsuchende Zeichenkette.
-
matches
-
Falls der Parameter
matches
angegeben wurde, wird er mit den Suchergebnissen gefüllt. $matches[0] enthält dann den Text, der auf das komplette Suchmuster passt, $matches[1] den Text, der auf das erste eingeklammerte Teilsuchmuster passt und so weiter. -
flags
-
flags
kann eine Kombination der folgenden Flags sein:-
PREG_OFFSET_CAPTURE
-
Wenn dieses Flag gesetzt ist, wird mit jeder gefundenen Übereinstimmung die dazugehörige Position in der Zeichenkette (in Bytes) zurückgegeben. Zu beachten ist, dass dies den Wert von
matches
in ein Array ändert, in dem jedes Element ein Array ist, das aus der übereinstimmenden Zeichenkette als Element0
und deren Stelle insubject
als Element1
besteht.<?php
preg_match('/(foo)(bar)(baz)/', 'foobarbaz', $matches, PREG_OFFSET_CAPTURE);
print_r($matches);
?>Das oben gezeigte Beispiel erzeugt folgende Ausgabe:
Array ( [0] => Array ( [0] => foobarbaz [1] => 0 ) [1] => Array ( [0] => foo [1] => 0 ) [2] => Array ( [0] => bar [1] => 3 ) [3] => Array ( [0] => baz [1] => 6 ) )
-
PREG_UNMATCHED_AS_NULL
-
Wird dieses Flag angegeben, werden nicht gefundene Teilsuchmuster als
null
zurückgegeben; andernfalls werden sie als eine leere Zeichenkette (String) zurückgegeben.<?php
preg_match('/(a)(b)*(c)/', 'ac', $matches);
var_dump($matches);
preg_match('/(a)(b)*(c)/', 'ac', $matches, PREG_UNMATCHED_AS_NULL);
var_dump($matches);
?>Das oben gezeigte Beispiel erzeugt folgende Ausgabe:
array(4) { [0]=> string(2) "ac" [1]=> string(1) "a" [2]=> string(0) "" [3]=> string(1) "c" } array(4) { [0]=> string(2) "ac" [1]=> string(1) "a" [2]=> NULL [3]=> string(1) "c" }
-
-
offset
-
Normalerweise beginnt die Suche am Anfang der Zeichenkette. Der optionale Parameter
offset
kann verwendet werden, um eine andere Stelle in Bytes anzugeben, ab der gesucht werden soll.Hinweis:
Die Verwendung von
offset
entspricht nicht der Übergabe vonsubstr($subject, $offset)
an Stelle der Zeichenkette an preg_match(), weilpattern
Angaben wie ^, $ oder (?<=x) enthalten kann. Vergleiche:<?php
$zeichenkette = "abcdef";
$suchmuster = '/^def/';
preg_match($suchmuster, $zeichenkette, $treffer, PREG_OFFSET_CAPTURE, 3);
print_r($treffer);
?>Das oben gezeigte Beispiel erzeugt folgende Ausgabe:
Array ( )
während dieses Beispiel
<?php
$zeichenkette = "abcdef";
$suchmuster = '/^def/';
preg_match($suchmuster, substr($zeichenkette,3), $treffer, PREG_OFFSET_CAPTURE);
print_r($treffer);
?>folgende Ausgabe erzeugt
Array ( [0] => Array ( [0] => def [1] => 0 ) )
Als Alternative, um die Verwendung von substr() zu vermeiden, kann die Assertion
\G
statt des Ankers^
verwendet werden, oder stattdessen der ModifikatorA
; beide funktionieren in Kombination mit dem Parameteroffset
.
Rückgabewerte
preg_match() gibt 1 zurück, falls eine Übereinstimmung
zwischen pattern
und subject
gefunden wurde, 0, falls nicht. Bei einem Fehler wird false
zurückgegeben.
Diese Funktion kann sowohl das
boolsche false
zurückliefern, als auch einen nicht-boolschen Wert, welcher zu false
ausgewertet wird.
Weitere Informationen entnehmen Sie bitte dem Abschnitt über die
boolschen Typen. Benutzen Sie deshalb
den === Operator,
um den Rückgabewert dieser Funktion zu überprüfen.
Fehler/Exceptions
Wenn das übergebene Regex-Muster nicht zu einem gültigen Regex kompiliert werden
kann, wird ein Fehler der Stufe E_WARNING
ausgegeben.
Changelog
Version | Beschreibung |
---|---|
7.2.0 |
Beim Parameter $flags wird nun die Konstante
PREG_UNMATCHED_AS_NULL unterstützt.
|
Beispiele
Beispiel #1 Die Zeichenkette "php" finden
<?php
// Das "i" nach der Suchmuster-Begrenzung kennzeichnet eine Suche ohne
// Berücksichtigung von Groß- und Kleinschreibung
if (preg_match("/php/i", "PHP ist die Web-Skriptsprache der Wahl.")) {
echo "Es wurde eine Übereinstimmung gefunden.";
} else {
echo "Es wurde keine Übereinstimmung gefunden.";
}
?>
Beispiel #2 Die Zeichenkette "web" finden
<?php
// Das \b im Suchmuster kennzeichnet eine Wortgrenze, weshalb nur eine
// Übereinstimmung mit der einzelnen Zeichenkette "web" gefunden wird und
// nicht ein Teilwort in "webbing" oder "cobweb"
if (preg_match("/\bweb\b/i", "Für das Web ist PHP die Skriptsprache der Wahl.")) {
echo "Es wurde eine Übereinstimmung gefunden.";
} else {
echo "Es wurde keine Übereinstimmung gefunden.";
}
if (preg_match("/\bweb\b/i", "PHP ist die Web-Skriptsprache der Wahl.")) {
echo "Es wurde eine Übereinstimmung gefunden.";
} else {
echo "Es wurde keine Übereinstimmung gefunden.";
}
?>
Beispiel #3 Den Domänen-Namen aus einer URL holen
<?php
// den Hostnamen aus URL holen
preg_match('@^(?:http://)?([^/]+)@i',
"http://www.php.net/index.html", $treffer);
$host = $treffer[1];
// die letzten beiden Segmente aus Hostnamen holen
preg_match('/[^.]+\.[^.]+$/', $host, $treffer);
echo "Der Domänen-Name lautet: {$treffer[0]}\n";
?>
Das oben gezeigte Beispiel erzeugt folgende Ausgabe:
Der Domänen-Name lautet: php.net
Beispiel #4 Benannte Teilsuchmuster (named subpatterns)
<?php
$str = 'foobar: 2008';
preg_match('/(?P<name>\w+): (?P<zahl>\d+)/', $str, $treffer);
/* Alternative */
// preg_match('/(?<name>\w+): (?<zahl>\d+)/', $str, $treffer);
print_r($treffer);
?>
Das oben gezeigte Beispiel erzeugt folgende Ausgabe:
Array ( [0] => foobar: 2008 [name] => foobar [1] => foobar [zahl] => 2008 [2] => 2008 )
Anmerkungen
Verwenden Sie nicht preg_match(), wenn Sie nur überprüfen wollen, ob eine Zeichenkette in einer anderen Zeichenkette enthalten ist. Verwenden Sie dafür stattdessen die Funktion strpos(), die das schneller erledigt.
Siehe auch
- PCRE-Suchmuster
- preg_quote() - Maskiert Zeichen regulärer Ausdrücke
- preg_match_all() - Führt eine vollständige Suche mit einem regulären Ausdruck durch
- preg_replace() - Sucht und ersetzt mit regulären Ausdrücken
- preg_split() - Zerlegt eine Zeichenkette anhand eines regulären Ausdrucks
- preg_last_error() - Liefert den Fehlercode der letzten PCRE-RegEx-Auswertung
- preg_last_error_msg() - Returns the error message of the last PCRE regex execution