# preg_match_all

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

preg_match_all — Expression rationnelle globale

### Description

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

Analyse `subject` pour trouver l'expression `pattern` et met les résultats dans `matches`, dans l'ordre spécifié par `flags`.

Après avoir trouvé un premier résultat, la recherche continue jusqu'à la fin de la chaîne.

### Liste de paramètres

`pattern`

  Le masque à chercher, sous la forme d'une chaîne de caractères.

`subject`

  La chaîne d'entrée.

`matches`

  Tableau contenant tous les résultats, dans un tableau multidimensionnel ordonné suivant le paramètre `flags`.

`flags`

  Peut être une combinaison des valeurs suivantes (notez bien qu'il est incohérent d'utiliser `PREG_PATTERN_ORDER` avec `PREG_SET_ORDER` ) :

  `PREG_PATTERN_ORDER`

    L'ordre est tel que $matches[0] est un tableau qui contient les résultats qui satisfont le masque complet, $matches[1] est un tableau qui contient les résultats qui satisfont la première parenthèse capturante, etc.

    `<?php
    preg_match_all("|<[^>]+>(.*)</[^>]+>|U",
    "<b>exemple : </b><div align=left>ceci est un test</div>",
    $out, PREG_PATTERN_ORDER);
    echo $out[0][0] . ", " . $out[0][1] . "\n";
    echo $out[1][0] . ", " . $out[1][1] . "\n";
    ?>`

    L'exemple ci-dessus va afficher :

        <b>exemple : </b>, <div align=left>ceci est un test</div>
        exemple : , ceci est un test

    Ainsi, $out[0] est un tableau qui contient les résultats qui satisfont le masque complet, et $out[1] est un tableau qui contient les balises entre > et <.

    Si le masque contient des sous-masque nommés, $matches contiendra en plus des entrées qui auront pour clés les noms des sous-masques.

    Si le masque contient des sous-masques nommés en double, seul le sous-masque le plus à droite sera enregistré dans $matches[NAME].

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

    L'exemple ci-dessus va afficher :

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

  `PREG_SET_ORDER`

    Les résultats sont classés de telle façon que $matches[0] contient la première série de résultats, $matches[1] contient la deuxième, etc.

    `<?php
    preg_match_all("|<[^>]+>(.*)</[^>]+>|U",
    "<b>exemple : </b><div align=\"left\">ceci est un test</div>",
    $out, PREG_SET_ORDER);
    echo $out[0][0] . ", " . $out[0][1] . "\n";
    echo $out[1][0] . ", " . $out[1][1] . "\n";
    ?>`

    L'exemple ci-dessus va afficher :

        <b>exemple : </b>, exemple :
        <div align="left">ceci est un test</div>, ceci est un test

  `PREG_OFFSET_CAPTURE`

    Si ce drapeau est passé, toutes les sous-chaînes qui satisfont le masque seront aussi identifiées par leur offset (en octets). Notez que cela modifie la valeur de `matches` en un tableau de tableau où chaque élément est un tableau contenant la sous-chaîne satisfaite à l'index `0` et l'index de celle-ci dans la chaîne `subject` à l'index `1`.

    `<?php
    preg_match_all('/(foo)(bar)(baz)/', 'foobarbaz', $matches, PREG_OFFSET_CAPTURE);
    print_r($matches);
    ?>`

    L'exemple ci-dessus va afficher :

        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`

    Si ce drapeau est passé, les sous-masques non satisfait sont rapportés en tant que `null` ; sinon ils sont rapportés en tant que chaîne de caractères vide.

  Si `order` est omis, `PREG_PATTERN_ORDER` est utilisé par défaut.

`offset`

  Normalement, la recherche commence au début de la chaîne `subject`. Le paramètre optionnel `offset` peut être utilisé pour spécifier une position pour le début de la recherche (en octets).

  > Note:

  > Utiliser le paramètre `offset` ne revient pas à passer `substr($subject, $offset)` à preg_match_all() à la place de la chaîne `subject`, car `pattern` peut contenir des assertions comme ^, $ ou (?<=x). Lisez la documentation sur la fonction preg_match() pour des exemples.

### Valeurs de retour

Retourne le nombre de résultats qui satisfont le masque complet, ou `false` si une erreur survient.

### Erreurs / Exceptions

Si le masque regex passé ne compile pas à une regex valide, une `E_WARNING` est émise.

### Historique

Version | Description
--- | ---
7.2.0 | `PREG_UNMATCHED_AS_NULL` est maintenant supporté pour le paramètre `$flags`.

### Exemples

Exemple #1 Extraction de tous les numéros de téléphone d'un texte

`<?php
preg_match_all("/\(? (\d{3})? \)? (?(1) [\-\s] ) \d{3}-\d{4}/x",
"Call 555-1212 or 1-800-555-1212", $phones);
?>`

Exemple #2 Recherche les couples de balises HTML (gourmand)

`<?php
// Cet exemple utilise les références arrières (\\2).
// Elles indiquent à l'analyseur qu'il doit trouver quelque chose qu'il
// a déjà repéré un peu plus tôt
// le nombre 2 indique que c'est le deuxième jeu de parenthèses
// capturante qui doit être utilisé (ici, ([\w]+)).
// L'antislash est nécessaire ici, car la chaîne est entre guillemets doubles
$html = "<b>texte en gras</b><a href=howdy.html>cliquez moi</a>";
preg_match_all("/(<([\w]+)[^>]*>)(.*?)(<\/\\2>)/", $html, $matches, PREG_SET_ORDER);
foreach ($matches as $val) {
echo "matched: " . $val[0] . "\n";
echo "part 1: " . $val[1] . "\n";
echo "part 2: " . $val[2] . "\n";
echo "part 3: " . $val[3] . "\n";
echo "part 4: " . $val[4] . "\n\n";
}
?>`

L'exemple ci-dessus va afficher :

    matched: <b>texte en gras</b>
    part 2: b
    part 3: texte en gras
    part 4: </b>

    matched: <a href=howdy.html>cliquez moi</a>
    part 1: <a href=howdy.html>
    part 2: a
    part 3: cliquez moi
    part 4: </a>

Exemple #3 Utilisation d'un sous-masque nommé

`<?php
$str = <<<FOO
a: 1
b: 2
c: 3
FOO;
preg_match_all('/(?P<name>\w+): (?P<digit>\d+)/', $str, $matches);
/* Alternative */
// preg_match_all('/(?<name>\w+): (?<digit>\d+)/', $str, $matches);
print_r($matches);
?>`

L'exemple ci-dessus va afficher :

    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
            )

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

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

    )

### Voir aussi

- Masques PCRE
- preg_quote() - Protection des caractères spéciaux des expressions régulières
- preg_match() - Effectue une recherche de correspondance avec une expression rationnelle standard
- preg_replace() - Rechercher et remplacer par expression rationnelle standard
- preg_split() - Éclate une chaîne par expression rationnelle
- preg_last_error() - Retourne le code erreur de la dernière expression PCRE exécutée