preg_replace_callback

Introduction

preg_replace_callback() effectue une recherche-remplacement par expression régulière, mais au lieu de fournir une chaîne de remplacement fixe, vous lui passez une fonction de rappel (callback) qui est exécutée pour chaque correspondance. Le callback reçoit la correspondance (et les éventuels groupes de capture) et renvoie le texte à substituer. Cela vous permet de calculer des remplacements avec de la logique PHP réelle — mettre un mot en majuscules, ajouter 1 à un nombre, rechercher une valeur dans une table — ce que la fonction preg_replace() classique ne peut pas faire.

Utilisez-la chaque fois que le remplacement dépend de ce qui a été trouvé. Si votre remplacement est une constante ou une simple référence arrière comme $1, préférez preg_replace() ; si vous avez besoin d'un callback différent par motif, consultez preg_replace_callback_array().

Syntaxe

preg_replace_callback(
    string|array $pattern,
    callable $callback,
    string|array $subject,
    int $limit = -1,
    int &$count = null,
    int $flags = 0
): string|array|null

La fonction renvoie le sujet modifié, ou null en cas d'erreur de regex. Le premier argument du callback est le tableau $matches : $matches[0] est la correspondance entière et $matches[1], $matches[2], … sont les groupes capturés — exactement comme le tableau que preg_match() remplit.

Exemple de base : mettre chaque mot en majuscules

Le motif \w+ correspond à chaque suite de caractères de mot. Pour chaque correspondance, le callback reçoit $matches[0] (le mot) et renvoie sa forme en majuscules, qui est réinsérée dans la chaîne.

Travailler avec les groupes de capture

Les parenthèses dans le motif créent des groupes de capture qui apparaissent à $matches[1], $matches[2], et ainsi de suite. Ici, nous ajoutons un à chaque nombre dans une chaîne :

<?php

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

$result = preg_replace_callback('/(\d+)/', function ($m) {
    return (string) ((int) $m[1] + 1);
}, $subject);

echo $result;
// Room 13, floor 4, building 8

Comme le callback exécute du vrai code, l'incrémentation est calculée pour chaque correspondance — quelque chose qu'une chaîne de remplacement statique ne peut jamais exprimer.

Un cas d'usage pratique : masquer des données sensibles

Une tâche courante consiste à cacher partiellement des adresses e-mail ou des numéros de carte dans les journaux. Le callback peut décider quelle partie de chaque correspondance révéler :

<?php

$text = 'Contact: [email protected] or [email protected]';

$result = preg_replace_callback('/([\w.]+)@([\w.]+)/', function ($m) {
    $name = $m[1];
    $masked = $name[0] . str_repeat('*', max(strlen($name) - 1, 1));
    return $masked . '@' . $m[2];
}, $text);

echo $result;
// Contact: a****@example.com or b**@test.org

Compter et limiter les remplacements

Les paramètres $limit et $count vous permettent de plafonner le nombre de correspondances traitées et de savoir combien l'ont réellement été :

<?php

$subject = 'a a a a a';

$result = preg_replace_callback('/a/', function ($m) {
    return 'b';
}, $subject, 2, $count);

echo $result, "\n"; // b b a a a
echo $count;        // 2

Seuls les deux premiers a sont remplacés car $limit vaut 2, et $count indique le nombre de remplacements effectués.

preg_replace vs. preg_replace_callback

Pour rechercher sans remplacer, consultez preg_match() et preg_match_all(), ainsi que le chapitre expressions régulières PHP pour la syntaxe des motifs.

Pièges courants

• Toujours retourner une chaîne. La valeur de retour du callback est convertie en chaîne et insérée. Retourner null supprime la correspondance ; oublier return insère une chaîne vide.
• Référencer le bon index. $matches[0] est la correspondance complète ; le groupe 1 se trouve à $matches[1]. Un décalage d'un est le bug le plus fréquent.
• Échapper avec précaution. Contrairement à preg_replace(), vous n'écrivez pas de références arrières $1/\1 dans le résultat — vous construisez la chaîne vous-même, donc il n'y a rien à échapper dans le remplacement.
• Une valeur de retour null de la fonction elle-même (pas du callback) signale une erreur de regex, comme un délimiteur non fermé.

Conclusion

preg_replace_callback() est le bon outil chaque fois qu'un remplacement doit être calculé plutôt qu'énoncé. Elle associe la puissance de correspondance des expressions régulières à une logique PHP arbitraire dans le callback, ce qui la rend idéale pour transformer, masquer ou recalculer le texte correspondant. Pour les remplacements statiques, restez avec preg_replace(), et pour plusieurs motifs à la fois, utilisez preg_replace_callback_array().

Pratique