# preg_match

(PHP 4, PHP 5, PHP 7, PHP 8)

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

### Beschreibung

preg_match(
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 Element `0` und deren Stelle in `subject` als Element `1` 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 von `substr($subject, $offset)` an Stelle der Zeichenkette an preg_match(), weil `pattern` 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 Modifikator `A`; beide funktionieren in Kombination mit dem Parameter `offset`.

### 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.

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.

### 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.";
}
echo "\n";
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

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() - 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

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open