preg_match_all()

Introduction

En PHP, les expressions régulières sont indispensables pour rechercher et manipuler des chaînes. Tandis que preg_match() s'arrête à la première correspondance, preg_match_all() continue à analyser et retourne toutes les occurrences d'un motif dans une chaîne. Utilisez-la chaque fois que vous devez extraire tous les numéros de téléphone, toutes les balises, tous les mots, ou toute structure répétitive d'un texte.

Cet article explique la syntaxe, l'argument $flags — qui contrôle la disposition des résultats — ainsi que plusieurs exemples pratiques.

Syntaxe

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

• $pattern — l'expression régulière, délimitée par /.../ (ou tout autre délimiteur correspondant).
• $subject — la chaîne dans laquelle effectuer la recherche.
• $matches — un tableau de sortie (passé par référence) rempli avec toutes les correspondances trouvées.
• $flags — optionnel. Contrôle la structure de $matches (voir ci-dessous).
• $offset — optionnel. Décalage en octets dans $subject à partir duquel commencer la recherche.

La fonction retourne le nombre de correspondances complètes (qui peut être 0), ou false si le motif est invalide.

Une correspondance simple

L'utilisation la plus basique consiste à collecter chaque sous-chaîne correspondant à un motif. Ici, nous extrayons tous les nombres d'une phrase :

<?php

$subject = 'Room 12, floor 3, building 7';

$count = preg_match_all('/\d+/', $subject, $matches);

echo "Found $count numbers\n";
print_r($matches[0]);

Résultat :

Found 3 numbers
Array
(
    [0] => 12
    [1] => 3
    [2] => 7
)

Lorsque le motif ne comporte pas de groupes capturants, $matches[0] contient la liste des correspondances complètes.

Choisir un drapeau : PREG_PATTERN_ORDER vs PREG_SET_ORDER

L'argument $flags détermine comment les correspondances et les groupes capturants sont organisés. Les deux drapeaux principaux sont mutuellement exclusifs :

• PREG_PATTERN_ORDER (valeur par défaut) — $matches[0] contient toutes les correspondances complètes, $matches[1] toutes les captures du groupe 1, $matches[2] toutes les captures du groupe 2, etc. Pensez « colonne par colonne ».
• PREG_SET_ORDER — $matches[0] est la première correspondance complète (correspondance complète + ses groupes), $matches[1] est la deuxième, etc. Pensez « ligne par ligne ».

Vous pouvez également ajouter PREG_OFFSET_CAPTURE pour enregistrer le décalage en octets de chaque correspondance en même temps que son texte.

PREG_SET_ORDER (grouper les résultats par occurrence)

Cette disposition est la plus facile à parcourir en boucle lorsque chaque correspondance possède plusieurs groupes capturants :

Résultat :

Name: Alice, Age: 25
Name: Bob, Age: 30

Avec PREG_SET_ORDER, chaque $match représente une occurrence : $match[0] est la correspondance complète, $match[1] est le premier groupe (nom), $match[2] est le second groupe (âge).

PREG_PATTERN_ORDER (grouper les résultats par motif)

Le même motif avec le drapeau par défaut retourne les groupes sous forme de tableaux parallèles :

<?php

$pattern = '/([A-Z][a-z]+) (\d+)/';
$subject = 'Alice 25 Bob 30';

preg_match_all($pattern, $subject, $matches, PREG_PATTERN_ORDER);

print_r($matches[1]); // all names
print_r($matches[2]); // all ages

Résultat :

Array
(
    [0] => Alice
    [1] => Bob
)
Array
(
    [0] => 25
    [1] => 30
)

Groupes capturants nommés

Nommer les groupes avec (?<name>...) rend le résultat autodocumenté — les noms deviennent des clés de tableau (en plus des index numériques) :

<?php

$pattern = '/(?<name>[A-Z][a-z]+) (?<age>\d+)/';
$subject = 'Alice 25 Bob 30';

preg_match_all($pattern, $subject, $matches, PREG_SET_ORDER);

foreach ($matches as $match) {
  echo "{$match['name']} is {$match['age']}\n";
}

Résultat :

Alice is 25
Bob is 30

Pièges courants

• Vérifiez la valeur de retour, pas le tableau. Un motif peut correspondre zéro fois et réussir quand même ; preg_match_all() retourne 0, tandis que false signifie que l'expression régulière elle-même était invalide. Utilisez === false pour détecter les erreurs. Consultez preg_last_error() pour connaître la raison précise de l'échec.
• $matches est écrasé. Chaque appel remplace le contenu précédent du tableau de sortie.
• Choisissez le bon drapeau pour votre boucle. Utilisez PREG_SET_ORDER lorsque vous voulez une ligne par correspondance ; utilisez le PREG_PATTERN_ORDER par défaut lorsque vous voulez une colonne par groupe.
• Échappez les caractères spéciaux dans les motifs dynamiques avec preg_quote() lorsque le motif provient d'une entrée utilisateur.

Conclusion

preg_match_all() retourne toutes les correspondances d'un motif dans une chaîne, ce qui en fait la fonction de référence pour extraire des données répétitives. La clé pour bien l'utiliser est de comprendre l'argument $flags : PREG_SET_ORDER regroupe les résultats par occurrence, tandis que le PREG_PATTERN_ORDER par défaut les regroupe par groupe capturant.

Pour les outils associés, consultez preg_match() pour une correspondance unique, preg_replace() pour la recherche et le remplacement, et preg_split() pour diviser des chaînes selon un motif.

Pratique