preg_match

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

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

Description

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.

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

Exemples

Exemple #1 Trouve la chaîne "php"

Exemple #2 Trouve le mot "web"

Exemple #3 Lire un nom de domaine dans une URL

L'exemple ci-dessus va afficher :

Le nom de domaine est : php.net

Exemple #4 Utilisation des sous-masques nommés

L'exemple ci-dessus va afficher :

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

Notes

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() - Returns the error message of the last PCRE regex execution