Función PHP: array_replace_recursive()

La función array_replace_recursive() en PHP fusiona arrays manteniendo intactos la estructura y las claves de los arrays originales. Reemplaza elementos del primer array con elementos de los arrays siguientes, descendiendo hacia los arrays anidados a medida que avanza. Esto la convierte en la herramienta adecuada cuando necesitas superponer un array multidimensional sobre otro — por ejemplo, aplicar configuraciones del usuario sobre una configuración predeterminada sin aplanar los datos anidados.

Este capítulo cubre la sintaxis de la función, cómo se comporta realmente la recursión, varios ejemplos prácticos (incluidos múltiples arrays de reemplazo) y cómo se diferencia de funciones relacionadas como array_replace() y array_merge_recursive().

Sintaxis

La sintaxis de la función array_replace_recursive() es sencilla: el primer argumento es el array que se modificará y los argumentos siguientes son arrays cuyos elementos se fusionarán en el primero.

Sintaxis de la función PHP array_replace_recursive

array_replace_recursive(array $array, array ...$replacements): array

El primer argumento es el array base. Cada array posterior se aplica sobre él de izquierda a derecha, de modo que un valor en un array posterior prevalece sobre la misma clave en uno anterior. La función devuelve un array nuevo y no modifica los argumentos en el lugar.

Cómo funciona

La función array_replace_recursive() funciona iterando sobre todos los elementos de los arrays pasados como argumentos. Para cada elemento, la función comprueba si la clave existe en el primer array. Si la clave no existe, el elemento simplemente se añade al primer array. Si la clave existe, la función comprueba si el valor es un array. Si lo es, la función se llama a sí misma de forma recursiva con el valor actual del primer array y el valor correspondiente del segundo array como argumentos. Si el valor no es un array, simplemente se reemplaza con el valor del segundo array.

Este proceso se repite para todos los arrays siguientes pasados como argumentos, añadiendo o reemplazando elementos en el primer array según sea necesario. El resultado final es un único array que resulta de fusionar todos los elementos de los arrays de entrada. Nota: a diferencia de array_merge_recursive(), esta función reemplaza las claves numéricas en lugar de fusionarlas por índice.

Ejemplos

A continuación se presentan algunos ejemplos de cómo se puede usar la función array_replace_recursive() en la práctica:

Ejemplo PHP de uso de la función array_replace_recursive

La salida de este código será:

Array
(
    [a] => Array
        (
            [b] => d
        )
)

La recursión se activa porque tanto $array1['a'] como $array2['a'] son arrays, por lo que la función desciende en ellos y reemplaza b en lugar de sobrescribir toda la rama a.

Otro ejemplo:

PHP Otro ejemplo de uso de la función array_replace_recursive

La salida de este código será:

Array
(
    [a] => d
)

Aquí la recursión no se produce: $array2['a'] es el string escalar 'd', no un array. Cuando el valor de reemplazo no es un array, el valor existente completo (incluido cualquier array anidado) se sobrescribe por completo. La función solo recursa cuando el valor existe como array en ambos lados.

Fusionar múltiples arrays y añadir nuevas claves

Puedes pasar cualquier número de arrays de reemplazo. Se aplican en orden, y las claves que aún no existen se añaden en lugar de reemplazarse.

PHP array_replace_recursive con múltiples arrays

<?php

$defaults = ['db' => ['host' => 'localhost', 'port' => 3306]];
$env      = ['db' => ['host' => 'db.internal']];
$cli      = ['db' => ['port' => 5432], 'debug' => true];

$result = array_replace_recursive($defaults, $env, $cli);

print_r($result);

?>

La salida de este código será:

Array
(
    [db] => Array
        (
            [host] => db.internal
            [port] => 5432
        )

    [debug] => 1
)

Las claves anidadas host y port son reemplazadas individualmente por los arrays posteriores, mientras que la nueva clave debug se añade al final. Esta superposición de izquierda a derecha es exactamente lo que hace que la función sea tan útil para configuraciones en capas.

array_replace_recursive() vs. funciones relacionadas

• array_replace() realiza la misma superposición pero solo en el nivel superior — nunca desciende a arrays anidados, por lo que un valor anidado siempre se reemplaza en su totalidad.
• array_merge_recursive() combina valores que comparten una clave (convirtiendo dos escalares en un array de ambos) en lugar de reemplazarlos, y renumera las claves enteras. array_replace_recursive() conserva un único valor de reemplazo y preserva las claves originales.
• array_merge() es la fusión no recursiva que también renumera las claves enteras.

Si tu objetivo es "tomar estos valores predeterminados y sobrescribirlos con estos otros valores", usa array_replace_recursive(). Si tu objetivo es "recopilar todo bajo cada clave", usa array_merge_recursive().

Conclusión

En conclusión, la función array_replace_recursive() en PHP ofrece una forma conveniente de fusionar arrays preservando su estructura y claves originales. Es especialmente valiosa para actualizar datos de configuración anidados o fusionar conjuntos de datos estructurados sin iteración manual.

Práctica