# preg_match

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

preg_match — Effectue une recherche de correspondance avec une expression rationnelle standard

### Description

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

Analyse `subject` pour trouver l'expression qui correspond à `pattern`.

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

  Si `matches` est fourni, il sera rempli par les résultats de la recherche. $matches[0] contiendra le texte qui satisfait le masque complet, $matches[1] contiendra le texte qui satisfait la première parenthèse capturante, etc.

`flags`

  Le paramètre `flags` peut être une combinaison des drapeaux suivants :

  `PREG_OFFSET_CAPTURE`

    Si cette option est activée, 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` qui devient un tableau dont chaque élément est un tableau contenant la chaîne correspondant au masque à l'offset `0` ainsi que l'offset de la chaîne dans `subject` à l'offset `1`.

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

    L'exemple ci-dessus va afficher :

        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`

    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.

    `<?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);
    ?>`

    L'exemple ci-dessus va afficher :

        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`

  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). Comparez :

  > `<?php
  > $subject = "abcdef";
  > $pattern = '/^def/';
  > preg_match($pattern, $subject, $matches, PREG_OFFSET_CAPTURE, 3);
  > print_r($matches);
  > ?>`

  > L'exemple ci-dessus va afficher :

  >     Array
  >     (
  >     )

  > avec cet exemple :

  > `<?php
  > $subject = "abcdef";
  > $pattern = '/^def/';
  > preg_match($pattern, substr($subject,3), $matches, PREG_OFFSET_CAPTURE);
  > print_r($matches);
  > ?>`

  > produira :

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

  >     )

  > Sinon, pour éviter l'usage de substr(), utiliser l'assertion `\G` plutôt que l'ancre `^`, ou le modificateur `A`, tous les deux fonctionne avec le paramètre `offset`.

### Valeurs de retour

preg_match() retourne 1 si le `pattern` fourni correspond, 0 s'il ne correspond pas, ou `false` si une erreur survient.

Avertissement

Cette fonction peut retourner `false`, mais elle peut aussi retourner une valeur équivalent à `false`. Veuillez lire la section sur les booléens pour plus d'informations. Utilisez l'opérateur === pour tester la valeur de retour exacte de cette fonction.

### 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 Trouve la chaîne "php"

`<?php
// Le "i" après le délimiteur du pattern indique que la recherche ne sera pas sensible à la casse
if (preg_match("/php/i", "PHP est le meilleur langage de script du web.")) {
echo "Un résultat a été trouvé.";
} else {
echo "Aucun résultat n'a été trouvé.";
}
?>`

Exemple #2 Trouve le mot "web"

`<?php
/* \b, dans le masque, indique une limite de mot, de façon à ce que le mot
"web" uniquement soit repéré, et pas seulement des parties de mots comme
dans "webbing" ou "cobweb" */
if (preg_match("/\bweb\b/i", "PHP est le meilleur langage de script du web.")) {
echo "Le mot a été trouvé.";
} else {
echo "Le mot n'a pas été trouvé.";
}
echo "\n";
if (preg_match("/\bweb\b/i", "PHP est le meilleur langage de script du web.")) {
echo "Le mot a été trouvé.";
} else {
echo "Le mot n'a pas été trouvé.";
}
?>`

Exemple #3 Lire un nom de domaine dans une URL

`<?php
// repérer le nom de l'hôte dans l'URL
preg_match('@^(?:http://)?([^/]+)@i',
"http://www.php.net/index.html", $matches);
$host = $matches[1];
// repérer les deux derniers segments du nom de l'hôte
preg_match('/[^.]+\.[^.]+$/', $host, $matches);
echo "Le nom de domaine est : {$matches[0]}\n";
?>`

L'exemple ci-dessus va afficher :

    Le nom de domaine est : php.net

Exemple #4 Utilisation des sous-masques nommés

`<?php
$str = 'foobar: 2008';
preg_match('/(?P<name>\w+): (?P<digit>\d+)/', $str, $matches);
/* Alternative */
// preg_match('/(?<name>\w+): (?<digit>\d+)/', $str, $matches);
print_r($matches);
?>`

L'exemple ci-dessus va afficher :

    Array
    (
        [0] => foobar: 2008
        [name] => foobar
        [1] => foobar
        [digit] => 2008
        [2] => 2008
    )

### Notes

Astuce

N'utilisez pas preg_match() si vous voulez uniquement savoir si une chaîne est contenue dans une autre. Utilisez strpos() à la place car ça sera plus rapide.

### Voir aussi

- Masques PCRE
- preg_quote() - Protection des caractères spéciaux des expressions régulières
- preg_match_all() - Expression rationnelle globale
- 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
- preg_last_error_msg() - Renvoie le message d'erreur de la dernière exécution de regex PCRE