preg_replace_callback_array

Introducción

En PHP, las expresiones regulares son una herramienta esencial para buscar, comparar y transformar cadenas. Disponible desde PHP 7.1, la función preg_replace_callback_array() permite reemplazar todas las coincidencias de varios patrones de expresión regular en una sola llamada, donde cada patrón tiene su propio callback que calcula el reemplazo. Es la versión basada en arrays de preg_replace_callback(): en lugar de pasar un patrón y un callback, se pasa un mapa de pares pattern => callback.

Este capítulo explica qué devuelve la función, describe sus parámetros y muestra ejemplos ejecutables, incluyendo los errores más comunes relacionados con el orden de los patrones y los tipos de retorno.

Cuándo usarla

Usa preg_replace_callback_array() cuando:

• Necesites aplicar lógica de reemplazo diferente a distintos patrones en un solo recorrido sobre el sujeto.
• De lo contrario, encadenarías varias llamadas a preg_replace_callback() — condensarlas mejora la legibilidad y mantiene la intención en un solo lugar.
• El valor de reemplazo no puede expresarse como una cadena estática, por lo que preg_replace() no sirve — necesitas calcularlo a partir del texto coincidente.

Si solo tienes un patrón, usa preg_replace_callback(). Si los reemplazos son cadenas fijas, usa preg_replace().

Sintaxis

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: si $subject es una cadena, se devuelve una cadena; si $subject es un array, se devuelve un array. En caso de error de regex, devuelve null.

Nota: Los callbacks deben devolver una cadena. Un valor de retorno numérico (como un int) se convierte automáticamente a cadena. Devolver null resulta en una cadena vacía.

Ejemplo básico

El primer callback convierte a mayúsculas cada palabra; el segundo incrementa cada secuencia de dígitos. Ambos patrones se aplican al mismo sujeto en una sola llamada.

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

Aquí $matches[0] es el texto completo coincidente del patrón. El segundo callback devuelve un entero (1234 + 1), que PHP convierte a la cadena "1235".

El orden de los patrones importa

Los patrones se aplican en el orden del array, y cada uno se ejecuta sobre el resultado del anterior. Esto significa que un callback anterior puede cambiar el texto que ve un patrón posterior — una fuente habitual de sorpresas.

<?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 reordenases los dos patrones, las letras se convertirían a mayúsculas antes de que se ejecutara el patrón de dígitos — el resultado de los dígitos sería el mismo, pero en general el orden puede cambiar la salida.

Contar reemplazos con $count

Pasa una variable como cuarto argumento para saber cuántos reemplazos se realizaron en todos los patrones.

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

Trabajar con un array como sujeto

Cuando $subject es un array, la función procesa cada elemento y devuelve un array con la misma estructura.

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

Errores comunes

• Olvidar los delimitadores. Las claves deben ser cadenas regex válidas con delimitadores, p. ej. '/\d+/', no '\d+'. Un delimitador faltante hace que la llamada devuelva null y emita una advertencia.
• Devolver valores no-string intencionadamente. Aunque los retornos numéricos se convierten automáticamente, devolver arrays u objetos lanza un TypeError. Convierte o formatea el valor antes de devolverlo.
• Suponer que los patrones son independientes. Como se muestra arriba, cada patrón opera sobre la salida del anterior. Ordena el mapa de forma deliberada.
• Confundir grupos de captura con la coincidencia completa. $matches[0] es la coincidencia completa; $matches[1], $matches[2], … son los grupos capturados. Referencia el índice correcto para tu lógica.

Funciones relacionadas

• preg_replace_callback() — patrón único + callback único.
• preg_replace() — reemplazar con cadenas estáticas o referencias hacia atrás.
• preg_match() y preg_match_all() — encontrar coincidencias sin reemplazar.
• Funciones callback de PHP — cómo funcionan los callables en PHP.

Conclusión

preg_replace_callback_array() proporciona una forma limpia y de un solo recorrido para aplicar lógica de reemplazo diferente a múltiples patrones regex. Destaca cuando cada patrón necesita su propio reemplazo calculado, sustituyendo lo que de otro modo serían varias llamadas encadenadas a preg_replace_callback(). Recuerda que los patrones se ejecutan en el orden del array y que los callbacks deben devolver cadenas, y la función mantendrá tu código de transformación de texto compacto y legible.

Práctica