preg_replace_callback_array

Introdução

Em PHP, as expressões regulares são uma ferramenta essencial para corresponder, pesquisar e transformar strings. Disponível desde o PHP 7.1, a função preg_replace_callback_array() permite substituir todas as correspondências de vários padrões de expressão regular em uma única chamada, onde cada padrão tem seu próprio callback que calcula a substituição. É a irmã orientada a arrays de preg_replace_callback(): em vez de passar um padrão e um callback, você passa um mapa de pares padrão => callback.

Este capítulo explica o que a função retorna, percorre seus parâmetros e mostra exemplos executáveis — incluindo as armadilhas comuns relacionadas à ordem dos padrões e aos tipos de retorno.

Quando usar

Use preg_replace_callback_array() quando:

• Você precisa aplicar lógica de substituição diferente para padrões diferentes em uma única passagem pelo sujeito.
• Você encadearia várias chamadas de preg_replace_callback() — agrupá-las mantém o código legível e a intenção em um único lugar.
• O valor de substituição não pode ser expresso como uma string estática, então o simples preg_replace() não é suficiente — você precisa calculá-lo a partir do texto correspondido.

Se você tiver apenas um único padrão, use preg_replace_callback(). Se as substituições forem strings fixas, use preg_replace().

Sintaxe

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

Valor de retorno: se $subject for uma string, uma string é retornada; se $subject for um array, um array é retornado. Em caso de erro de regex, retorna null.

Nota: Os callbacks devem retornar uma string. Um valor de retorno numérico (como um int) é automaticamente convertido para string. Retornar null resulta em uma string vazia.

Exemplo básico

O primeiro callback converte cada palavra para maiúsculas; o segundo incrementa cada sequência de dígitos. Ambos os padrões são aplicados ao mesmo sujeito em uma única chamada.

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

Aqui $matches[0] é o texto completo correspondido pelo padrão. O segundo callback retorna um inteiro (1234 + 1), que o PHP converte para a string "1235".

A ordem dos padrões importa

Os padrões são aplicados na ordem do array, e cada um é executado sobre o resultado do anterior. Isso significa que um callback anterior pode alterar o texto que um padrão posterior verá — uma fonte comum de surpresas.

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

Se você reordenasse os dois padrões, as letras seriam convertidas para maiúsculas antes de o padrão de dígitos ser executado — o resultado dos dígitos é o mesmo, mas em geral a ordem pode alterar a saída.

Contando substituições com $count

Passe uma variável como quarto argumento para saber quantas substituições ocorreram em todos os padrões.

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

Trabalhando com um array como sujeito

Quando $subject é um array, a função processa cada elemento e retorna um array com a mesma estrutura.

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

Armadilhas comuns

• Esquecer os delimitadores. As chaves devem ser strings regex válidas com delimitadores, por exemplo '/\d+/', não '\d+'. Um delimitador ausente faz a chamada retornar null e emitir um aviso.
• Retornar não-strings intencionalmente. Embora retornos numéricos sejam convertidos automaticamente, retornar arrays ou objetos dispara um TypeError. Converta ou formate seu valor antes de retorná-lo.
• Assumir que os padrões são independentes. Como mostrado acima, cada padrão opera sobre a saída do anterior. Ordene seu mapa deliberadamente.
• Usar grupos de captura vs. a correspondência completa. $matches[0] é a correspondência inteira; $matches[1], $matches[2], … são os grupos capturados. Referencie o índice correto para sua lógica.

Funções relacionadas

• preg_replace_callback() — padrão único + callback único.
• preg_replace() — substituir com strings estáticas ou referências inversas.
• preg_match() e preg_match_all() — encontrar correspondências sem substituir.
• Funções de callback PHP — como os callables funcionam em PHP.

Conclusão

preg_replace_callback_array() oferece uma forma limpa e de passagem única para aplicar lógica de substituição diferente a múltiplos padrões regex. Ela se destaca quando cada padrão precisa de sua própria substituição calculada, substituindo o que de outra forma seriam várias chamadas encadeadas de preg_replace_callback(). Lembre-se de que os padrões são executados na ordem do array e que os callbacks devem retornar strings, e a função manterá seu código de transformação de texto compacto e legível.

Prática