preg_replace_callback_array

Introduction

En PHP, les expressions régulières sont un outil essentiel pour rechercher, comparer et transformer des chaînes de caractères. Disponible depuis PHP 7.1, la fonction preg_replace_callback_array() vous permet de remplacer toutes les correspondances de plusieurs expressions régulières en un seul appel, chaque motif disposant de son propre callback pour calculer le remplacement. Il s'agit de la version orientée tableau de preg_replace_callback() : au lieu de passer un seul motif et un seul callback, vous passez un tableau associatif de paires motif => callback.

Ce chapitre explique ce que retourne la fonction, décrit ses paramètres et présente des exemples exécutables — y compris les pièges courants liés à l'ordre des motifs et aux types de retour.

Quand l'utiliser

Utilisez preg_replace_callback_array() quand :

• Vous devez appliquer une logique de remplacement différente selon les motifs en un seul parcours du sujet.
• Vous enchaîneriez sinon plusieurs appels à preg_replace_callback() — les regrouper rend le code plus lisible et centralise l'intention.
• La valeur de remplacement ne peut pas être exprimée comme une chaîne statique, donc preg_replace() ne suffit pas — vous avez besoin de la calculer à partir du texte correspondant.

Si vous n'avez qu'un seul motif, utilisez preg_replace_callback(). Si les remplacements sont des chaînes fixes, utilisez preg_replace().

Syntaxe

preg_replace_callback_array(
    array $pattern_and_callbacks,
    string|array $subject,
    int $limit = -1,
    int &$count = null,
    int $flags = 0
): string|array|null

Valeur de retour : si $subject est une chaîne, une chaîne est retournée ; si $subject est un tableau, un tableau est retourné. En cas d'erreur regex, la fonction retourne null.

Remarque : les callbacks doivent retourner une chaîne. Une valeur numérique (comme un int) est automatiquement convertie en chaîne. Retourner null produit une chaîne vide.

Exemple de base

Le premier callback met en majuscules chaque mot ; le second incrémente chaque séquence de chiffres. Les deux motifs sont appliqués au même sujet en un seul appel.

<?php

$patterns_and_callbacks = [
  '/[a-z]+/i' => function ($matches) {
    return strtoupper($matches[0]);
  },
  '/\d+/' => function ($matches) {
    return (int) $matches[0] + 1;
  },
];

$string = 'This is a test string with 1234';

echo preg_replace_callback_array($patterns_and_callbacks, $string);
// THIS IS A TEST STRING WITH 1235

Ici $matches[0] est le texte complet correspondant au motif. Le second callback retourne un entier (1234 + 1), que PHP convertit en chaîne "1235".

L'ordre des motifs est important

Les motifs sont appliqués dans l'ordre du tableau, et chacun opère sur le résultat du précédent. Cela signifie qu'un callback antérieur peut modifier le texte qu'un motif ultérieur verra — une source courante de surprises.

<?php

$subject = 'abc123';

$result = preg_replace_callback_array([
  // Runs first: wraps every digit run in brackets.
  '/\d+/' => fn ($m) => '[' . $m[0] . ']',
  // Runs second: now sees "abc[123]" and upper-cases the letters.
  '/[a-z]+/' => fn ($m) => strtoupper($m[0]),
], $subject);

echo $result;
// ABC[123]

Si vous inversez l'ordre des deux motifs, les lettres seraient mises en majuscules avant que le motif des chiffres ne s'exécute — le résultat des chiffres est identique, mais en général l'ordre peut modifier la sortie.

Compter les remplacements avec $count

Passez une variable comme quatrième argument pour savoir combien de remplacements ont été effectués sur l'ensemble des motifs.

<?php

$subject = 'cat dog cat bird cat';

$result = preg_replace_callback_array(
  ['/cat/' => fn ($m) => 'fish'],
  $subject,
  -1,
  $count
);

echo $result . "\n"; // fish dog fish bird fish
echo "Replacements: $count"; // Replacements: 3

Travailler avec un sujet tableau

Quand $subject est un tableau, la fonction traite chaque élément et retourne un tableau de la même structure.

<?php

$subjects = ['Order #12', 'Order #7'];

$result = preg_replace_callback_array(
  ['/\d+/' => fn ($m) => str_pad($m[0], 4, '0', STR_PAD_LEFT)],
  $subjects
);

print_r($result);
// Array
// (
//     [0] => Order #0012
//     [1] => Order #0007
// )

Pièges courants

• Oublier les délimiteurs. Les clés doivent être des chaînes regex valides avec délimiteurs, par exemple '/\d+/', et non '\d+'. Un délimiteur manquant fait retourner null à la fonction et émet un avertissement.
• Retourner des non-chaînes intentionnellement. Bien que les retours numériques soient automatiquement convertis, retourner des tableaux ou des objets déclenche une TypeError. Convertissez ou formatez votre valeur avant de la retourner.
• Supposer que les motifs sont indépendants. Comme illustré ci-dessus, chaque motif opère sur la sortie du précédent. Ordonnez votre tableau délibérément.
• Confondre groupes de capture et correspondance complète. $matches[0] est la correspondance entière ; $matches[1], $matches[2], … sont les groupes capturés. Référencez le bon indice pour votre logique.

Fonctions associées

• preg_replace_callback() — un seul motif + un seul callback.
• preg_replace() — remplacer par des chaînes statiques ou des références arrière.
• preg_match() et preg_match_all() — trouver des correspondances sans remplacer.
• PHP callback functions — comment fonctionnent les callables en PHP.

Conclusion

preg_replace_callback_array() offre un moyen propre et en un seul parcours d'appliquer une logique de remplacement différente à plusieurs motifs regex. Elle excelle lorsque chaque motif nécessite son propre remplacement calculé, remplaçant ce qui serait sinon plusieurs appels enchaînés à preg_replace_callback(). N'oubliez pas que les motifs s'exécutent dans l'ordre du tableau et que les callbacks doivent retourner des chaînes, et la fonction gardera votre code de transformation de texte compact et lisible.

Practice