preg_replace_callback

Introdução

preg_replace_callback() realiza uma busca e substituição com expressão regular, mas em vez de fornecer uma string de substituição fixa, você passa uma função de callback que é executada para cada correspondência. O callback recebe a correspondência (e quaisquer grupos de captura) e retorna o texto a ser substituído. Isso permite computar substituições com lógica PHP real — converter uma palavra para maiúsculas, somar 1 a um número, buscar um valor em uma tabela — o que a função simples preg_replace() não consegue fazer.

Use-a sempre que a substituição depender do que foi encontrado. Se a substituição for constante ou uma backreference simples como $1, use preg_replace(); se precisar de um callback diferente por padrão, consulte preg_replace_callback_array().

Sintaxe

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

Retorna o sujeito modificado, ou null se ocorrer um erro de regex. O primeiro argumento do callback é o array $matches: $matches[0] é a correspondência completa e $matches[1], $matches[2], … são os grupos capturados — exatamente como o array que preg_match() preenche.

Exemplo básico: converter cada palavra para maiúsculas

O padrão \w+ corresponde a cada sequência de caracteres de palavra. Para cada correspondência, o callback recebe $matches[0] (a palavra) e retorna sua forma em maiúsculas, que é inserida de volta na string.

Trabalhando com grupos de captura

Parênteses no padrão criam grupos de captura que aparecem em $matches[1], $matches[2] e assim por diante. Aqui somamos 1 a cada número em uma string:

<?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

Como o callback executa código real, o incremento é calculado por correspondência — algo que uma string de substituição estática nunca consegue expressar.

Um caso de uso prático: mascarar dados sensíveis

Uma tarefa comum é ocultar parcialmente e-mails ou números de cartão em logs. O callback pode decidir quanto de cada correspondência revelar:

<?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

Contando e limitando substituições

Os parâmetros $limit e $count permitem limitar quantas correspondências são processadas e saber quantas foram de fato realizadas:

<?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

Apenas os dois primeiros as são substituídos porque $limit é 2, e $count informa o número de substituições realizadas.

preg_replace vs. preg_replace_callback

Para correspondência sem substituição, consulte preg_match() e preg_match_all(), e o capítulo sobre expressões regulares em PHP para a sintaxe de padrões.

Erros comuns

• Sempre retorne uma string. O valor de retorno do callback é convertido em string e inserido. Retornar null remove a correspondência; esquecer o return insere uma string vazia.
• Referencie o índice correto. $matches[0] é a correspondência completa; o grupo 1 está em $matches[1]. Um erro de índice aqui é o bug mais frequente.
• Escape com cuidado. Ao contrário de preg_replace(), você não escreve backreferences $1/\1 no resultado — você constrói a string você mesmo, portanto não há nada a escapar na substituição.
• Um valor de retorno null da própria função (não do callback) indica um erro de regex, como um delimitador sem correspondência.

Conclusão

preg_replace_callback() é a ferramenta certa sempre que uma substituição precisa ser calculada em vez de declarada. Ela combina o poder de correspondência das expressões regulares com lógica PHP arbitrária no callback, tornando-a ideal para transformar, mascarar ou recalcular textos correspondidos. Para substituições estáticas, use preg_replace(), e para vários padrões de uma vez, use preg_replace_callback_array().

Prática