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

# preg_match_all

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

preg_match_all — Führt eine vollständige Suche mit einem regulären Ausdruck durch

### Beschreibung

function preg_match_all(
string `$pattern`,
string `$subject`,
array `&$matches` = `null`,
int `$flags` = 0,
int `$offset` = 0
): int|false

Durchsucht `subject` nach allen Übereinstimmungen mit dem in `pattern` angegebenen regulären Ausdruck und legt sie in der durch `flags` festgelegten Reihenfolge in `matches` ab.

Nachdem die erste Übereinstimmung gefunden wurde, wird die nachfolgende Suche jeweils am Ende der letzten Übereinstimmung fortgesetzt.

### Parameter-Liste

`pattern`

  Der Ausdruck, nach dem gesucht werden soll, als Zeichenkette.

`subject`

  Die zu durchsuchende Zeichenkette.

`matches`

  Ein mehrdimensionales Array mit allen gefundenen Übereinstimmungen, das den `flags` entsprechend sortiert ist.

`flags`
  Wenn kein Flag für die Anordnung angegeben ist, wird `PREG_PATTERN_ORDER` angenommen.

  Kann eine Kombination folgender Flags sein (es ist zu beachten, dass es keinen Sinn hat, `PREG_PATTERN_ORDER` zusammen mit `PREG_SET_ORDER` zu verwenden):

  `PREG_PATTERN_ORDER`

    Ordnet die Ergebnisse so an, dass $matches[0] ein Array von Übereinstimmungen mit dem kompletten Suchmuster ist, $matches[1] ein Array von Zeichenketten, die auf das erste eingeklammerte Teilsuchmuster passen und so weiter.

        <?php
        preg_match_all("|<[^>]+>(.*)</[^>]+>|U",
            "<b>Beispiel: </b><div align=left>das ist ein Test</div>",
            $ausgabe, PREG_PATTERN_ORDER);
        echo $ausgabe[0][0] . ", " . $ausgabe[0][1] . "\n";
        echo $ausgabe[1][0] . ", " . $ausgabe[1][1] . "\n";
        ?>

    Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

        <b>Beispiel: </b>, <div align=left>das ist ein Test</div>
        Beispiel: , das ist ein Test

    Also enthält $ausgabe[0] ein Array von Zeichenketten, die auf das komplette Suchmuster passen und $ausgabe[1] ein Array von Zeichenketten, die sich zwischen Tags befinden.

    Enthält das Suchmuster benannte Teilsuchmuster, dann enthält $matches zusätzlich Elemente mit dem Namen der Teilsuchmuster als Schlüssel.

    Enthält das Suchmuster doppelt benannte Teilsuchmuster, wird nur das letzte Teilsuchmuster in $matches[NAME] gespeichert.

        <?php
        preg_match_all(
            '/(?J)(?<match>foo)|(?<match>bar)/',
            'foo bar',
            $matches,
            PREG_PATTERN_ORDER
        );
        print_r($matches['match']);
        ?>

    Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

        Array
        (
            [0] =>
            [1] => bar
        )

  `PREG_SET_ORDER`

    Ordnet die Ergebnisse so an, dass $matches[0] ein Array aus dem ersten Satz von Übereinstimmungen ist, $matches[1] ein Array aus dem zweiten Satz von Übereinstimmungen und so weiter.

        <?php
        preg_match_all("|<[^>]+>(.*)</[^>]+>|U",
            "<b>Beispiel: </b><div align=\"left\">das ist ein Test</div>",
            $ausgabe, PREG_SET_ORDER);
        echo $ausgabe[0][0] . ", " . $ausgabe[0][1] . "\n";
        echo $ausgabe[1][0] . ", " . $ausgabe[1][1] . "\n";
        ?>

    Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

        <b>Beispiel: </b>, Beispiel:
        <div align="left">das ist ein Test</div>, das ist ein Test

  `PREG_OFFSET_CAPTURE`

    Wenn dieses Flag gesetzt ist, wird mit jeder gefundenen Übereinstimmung die dazugehörige Position (in Bytes) in der Zeichenkette zurückgegeben. Zu beachten ist, dass dies den Wert von `matches` in ein Array von Arrays ä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_all('/(foo)(bar)(baz)/', 'foobarbaz', $matches, PREG_OFFSET_CAPTURE);
        print_r($matches);
        ?>

    Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

        Array
        (
            [0] => Array
                (
                    [0] => Array
                        (
                            [0] => foobarbaz
                            [1] => 0
                        )

                )

            [1] => Array
                (
                    [0] => Array
                        (
                            [0] => foo
                            [1] => 0
                        )

                )

            [2] => Array
                (
                    [0] => Array
                        (
                            [0] => bar
                            [1] => 3
                        )

                )

            [3] => Array
                (
                    [0] => 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.

`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($zeichenkette, $versatz)` an Stelle der Zeichenkette an preg_match_all(), weil `pattern` Angaben wie ^, $ oder (?<=x) enthalten kann. Für Beispiele siehe preg_match().

### Rückgabewerte

Gibt die Anzahl der Übereinstimmungen mit dem kompletten Suchmuster zurück (die auch Null sein kann). Bei einem Fehler wird `false` zurückgegeben.

### 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 Alle Telefonnummern aus einem Text holen.

    <?php
    preg_match_all("/\(?  (\d{3})?  \)?  (?(1)  [\-\s] ) \d{3}-\d{4}/x",
                    "Wählen Sie 555-1212 oder 1-800-555-1212", $telefon);
    ?>

Beispiel #2 Zusammengehörende HTML-Tags finden (gierig)

    <?php
    // Das \\2 ist ein Beispiel für Rückreferenzierung. Es teilt pcre mit, dass
    // der reguläre Ausdruck auf den für das zweite Klammerpaar gefundenen
    // Ausdruck selbst, also in diesem Fall auf den für ([\w]+) gefundenen
    // Ausdruck passen muss.
    // Der zusätzliche Backslash wird wegen der doppelten Anführungsstriche
    // benötigt.
    $html = "<b>fett gedruckter Text</b><a href=howdy.html>klick mich an</a>";

    preg_match_all("/(<([\w]+)[^>]*>)(.*?)(<\/\\2>)/", $html, $treffer, PREG_SET_ORDER);

    foreach ($treffer as $wert) {
        echo "gefunden: " . $wert[0] . "\n";
        echo "Teil 1: " . $wert[1] . "\n";
        echo "Teil 2: " . $wert[2] . "\n";
        echo "Teil 3: " . $wert[3] . "\n";
        echo "Teil 4: " . $wert[4] . "\n\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    gefunden: <b>fett gedruckter Text</b>
    Teil 1: <b>
    Teil 2: b
    Teil 3: fett gedruckter Text
    Teil 4: </b>

    gefunden: <a href=howdy.html>klick mich an</a>
    Teil 1: <a href=howdy.html>
    Teil 2: a
    Teil 3: klick mich an
    Teil 4: </a>

Beispiel #3 Benannte Teilsuchmuster (named subpatterns)

    <?php

    $str = <<<FOO
    a: 1
    b: 2
    c: 3
    FOO;

    preg_match_all('/(?P<name>\w+): (?P<zahl>\d+)/', $str, $treffer);

    /* Alternative */
    // preg_match_all('/(?<name>\w+): (?<zahl>\d+)/', $str, $treffer);

    print_r($treffer);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [0] => Array
            (
                [0] => a: 1
                [1] => b: 2
                [2] => c: 3
            )

        [name] => Array
            (
                [0] => a
                [1] => b
                [2] => c
            )

        [1] => Array
            (
                [0] => a
                [1] => b
                [2] => c
            )

        [zahl] => Array
            (
                [0] => 1
                [1] => 2
                [2] => 3
            )

        [2] => Array
            (
                [0] => 1
                [1] => 2
                [2] => 3
            )

    )

### Siehe auch

- PCRE-Suchmuster
- preg_quote() - Maskiert Zeichen regulärer Ausdrücke
- preg_match() - Führt eine 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

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