PCRE-Funktionen
PHP-Handbuch

preg_match

Führt eine Suche mit einem regulären Ausdruck durch

Beschreibung

int preg_match ( string $pattern , string $subject [, array &$matches [, int $flags = 0 [, int $offset = 0 ]]] )

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 das folgende Flag sein:

PREG_OFFSET_CAPTURE
Wenn dieses Flag gesetzt ist, wird mit jeder gefundenen Übereinstimmung der dazugehörige Versatz in der Zeichenkette zurückgegeben. Beachten Sie, dass dies den Wert von matches in ein Array ändert, in dem jedes Element ein Array ist, das aus der übereinstimmenden Zeichenkette als Element 0 und deren Stelle in subject als Element 1 besteht.

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 von substr($subject, $offset) an Stelle der zu Zeichenkette an preg_match, weil pattern Angaben wie zum Beispiel ^, $ 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
        )
)

Rückgabewerte

preg_match gibt 1 zurück, falls eine Übereinstimmung zwischen pattern und subject gefunden wurde, 0, falls nicht oder FALSE, falls ein Fehler auftrat.

Warnung

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.

Changelog

Version Beschreibung
5.3.6 Gibt FALSE zurück, wenn offset größer als die Länge von subject ist.
5.2.2 Benannte Teilsuchmuster akzeptieren nun sowohl die Syntaxen (?<name>) und (?'name') als auch (?P<name>). Vorherige Versionen akzeptierten nur (?P<name>).

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-Scripting-Sprache 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 Scripting-Sprache 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-Scripting-Sprache 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);

/* Folgendes funktioniert ab PHP 5.2.2 (PCRE 7.0) ebenfalls, für die
 * Rückwärtskompatibilität wird aber die vorherige Form empfohlen. */
// 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

Tipp

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
  • preg_match_all
  • preg_replace
  • preg_split
  • preg_last_error