Función PHP: array_merge_recursive

La función array_merge_recursive() en PHP combina dos o más arrays en uno. Su característica definitoria es cómo maneja las claves string superpuestas: en lugar de dejar que un valor posterior sobreescriba uno anterior, fusiona ambos valores en un sub-array, recursando en los arrays anidados a medida que avanza. Esto la convierte en la herramienta adecuada cuando deseas conservar cada valor en lugar de que el último array gane.

Esta página cubre la sintaxis y los parámetros, cómo funciona realmente la fusión recursiva, en qué se diferencia de array_merge(), un caso de uso real y las trampas a tener en cuenta.

Sintaxis

array_merge_recursive(array $array1, array ...$arrays): array

Parámetros

• array1: El primer array de entrada.
• ...$arrays: Uno o más arrays adicionales para fusionar.

Valor de retorno

Devuelve el array fusionado resultante.

¿Cómo funciona array_merge_recursive?

La función aplica dos reglas diferentes según el tipo de clave:

• Las claves string que aparecen en más de un array se combinan. Si ambos valores son escalares, se agrupan en un nuevo sub-array; si ambos son arrays, la función recursa y los fusiona en el siguiente nivel inferior.
• Las claves enteras (numéricas) nunca se sobreescriben. Cada elemento con clave numérica se agrega y se renumera, por lo que nada se pierde y el resultado se reindexia desde 0.

Por eso la función es "recursiva": cada vez que encuentra dos arrays bajo la misma clave string, profundiza y repite la misma lógica de fusión en sus contenidos.

Nota: A diferencia de array_merge(), que sobreescribe los valores de las claves string superpuestas y reindexia las claves numéricas, array_merge_recursive() fusiona las claves string superpuestas en arrays anidados preservando cada valor.

A continuación se muestra un ejemplo de cómo funciona array_merge_recursive:

Ejemplo PHP de la función array_merge_recursive

La salida de este código será:

Array
(
    [color] => Array
        (
            [favorite] => Array
                (
                    [0] => red
                    [1] => green
                )
            [0] => blue
        )
    [0] => 5
    [1] => 10
)

Como puede ver, la función array_merge_recursive ha fusionado las claves superpuestas en los arrays de entrada en sub-arrays.

array_merge() vs. array_merge_recursive()

Ver las dos funciones una al lado de la otra hace que la diferencia sea concreta:

<?php

$defaults  = ["roles" => ["user"],   "name" => "Guest"];
$overrides = ["roles" => ["editor"], "name" => "Ann"];

print_r(array_merge($defaults, $overrides));
print_r(array_merge_recursive($defaults, $overrides));

?>

Array                       // array_merge(): later value wins
(
    [roles] => Array
        (
            [0] => editor
        )
    [name] => Ann
)
Array                       // array_merge_recursive(): both values kept
(
    [roles] => Array
        (
            [0] => user
            [1] => editor
        )
    [name] => Array
        (
            [0] => Guest
            [1] => Ann
        )
)

Observe que incluso name, un simple string, se convirtió en un array ["Guest", "Ann"]. Esa es la trampa principal que se cubre a continuación: la fusión recursiva convierte cada clave string repetida en una lista, lo quisieras o no.

Cuándo usar array_merge_recursive

Recurre a esta función cuando el objetivo es recopilar valores en lugar de elegir uno. Un caso común es agrupar datos; por ejemplo, construir un mapa de una categoría a todos sus elementos:

<?php

$result = [];
$products = [
    ["category" => "fruit",     "name" => "apple"],
    ["category" => "fruit",     "name" => "pear"],
    ["category" => "vegetable", "name" => "carrot"],
];

foreach ($products as $product) {
    $result = array_merge_recursive(
        $result,
        [$product["category"] => [$product["name"]]]
    );
}

print_r($result);

?>

Array
(
    [fruit] => Array
        (
            [0] => apple
            [1] => pear
        )
    [vegetable] => Array
        (
            [0] => carrot
        )
)

Trampas

• Las claves string se fusionan, las claves enteras se agregan. Una clave string repetida produce un sub-array incluso cuando ambos valores son escalares. Si en cambio deseas que los valores posteriores sobreescriban los anteriores, usa array_merge() o array_replace_recursive().
• Las claves numéricas no se preservan. Las claves enteras siempre se renumeran desde 0, por lo que no puedes usar array_merge_recursive() para fusionar dos arrays por sus claves numéricas. Usa el operador + (unión) si necesitas conservar las claves tal como están.
• Solo desciende en arrays. Si un lado es un escalar y el otro es un array bajo la misma clave, ambos simplemente se agrupan en una lista; el escalar no se fusiona dentro del array.

Funciones relacionadas

• array_merge() — fusión plana donde las claves string posteriores sobreescriben las anteriores.
• array_replace_recursive() — recursa como esta función pero reemplaza los valores en lugar de recopilarlos.
• array_combine() — construye un array a partir de un array de claves separado y un array de valores.

Conclusión

La función array_merge_recursive() es la opción correcta cuando deseas combinar valores bajo claves string compartidas en lugar de sobreescribirlas — agrupar, agregar o acumular datos entre arrays. Ten en cuenta sus dos reglas (las claves string se fusionan en listas, las claves enteras se reindexan) y elige array_merge() o array_replace_recursive() cuando necesites el comportamiento de último valor ganador.

Práctica