Função PHP: array_merge_recursive

A função array_merge_recursive() em PHP combina dois ou mais arrays em um só. Sua característica principal é como ela lida com chaves string sobrepostas: em vez de permitir que um valor posterior sobrescreva um anterior, ela mescla ambos os valores em um sub-array, recursando em arrays aninhados conforme necessário. Isso a torna a ferramenta ideal quando você deseja manter todos os valores em vez de deixar o último array prevalecer.

Esta página aborda a sintaxe e os parâmetros, como a mesclagem recursiva realmente funciona, como ela difere de array_merge(), um caso de uso real e os pontos de atenção.

Sintaxe

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

Parâmetros

• array1: O primeiro array de entrada.
• ...$arrays: Um ou mais arrays adicionais a serem mesclados.

Valor de Retorno

Retorna o array mesclado resultante.

Como funciona array_merge_recursive?

A função aplica duas regras diferentes dependendo do tipo de chave:

• Chaves string que aparecem em mais de um array são combinadas. Se ambos os valores forem escalares, eles são reunidos em um novo sub-array; se ambos forem arrays, a função recursa e os mescla no próximo nível abaixo.
• Chaves inteiras (numéricas) nunca são sobrescritas. Cada elemento com chave numérica é anexado e renumerado, portanto nada é perdido e o resultado é reindexado a partir de 0.

É por isso que a função é "recursiva": sempre que encontra dois arrays sob a mesma chave string, ela mergulha neles e repete a mesma lógica de mesclagem em seu conteúdo.

Nota: Ao contrário de array_merge(), que sobrescreve valores para chaves string sobrepostas e reindexas as chaves numéricas, array_merge_recursive() mescla chaves string sobrepostas em arrays aninhados, preservando todos os valores.

Aqui está um exemplo de como array_merge_recursive funciona:

Exemplo PHP da função array_merge_recursive

A saída deste código será:

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

Como você pode ver, a função array_merge_recursive mesclou as chaves sobrepostas dos arrays de entrada em sub-arrays.

array_merge() vs. array_merge_recursive()

Ver as duas funções lado a lado torna a diferença 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 até name, uma string simples, se tornou um array ["Guest", "Ann"]. Esse é o principal ponto de atenção abordado abaixo: a mesclagem recursiva transforma toda chave string repetida em uma lista, independentemente de você querer isso ou não.

Quando usar array_merge_recursive

Use esta função quando o objetivo é coletar valores em vez de escolher um. Um caso comum é agrupar dados — por exemplo, construir um mapa de uma categoria para todos os seus itens:

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

Pontos de Atenção

• Chaves string são mescladas, chaves inteiras são anexadas. Uma chave string repetida produz um sub-array mesmo quando ambos os valores são escalares. Se você quiser que valores posteriores sobrescrevam os anteriores, use array_merge() ou array_replace_recursive().
• Chaves numéricas não são preservadas. Chaves inteiras são sempre renumeradas a partir de 0, portanto você não pode usar array_merge_recursive() para mesclar dois arrays pelas suas chaves numéricas. Use o operador + (união) se precisar manter as chaves como estão.
• A função só desce em arrays. Se um lado for um escalar e o outro for um array sob a mesma chave, ambos são simplesmente reunidos em uma lista; o escalar não é mesclado dentro do array.

Funções Relacionadas

• array_merge() — mesclagem simples onde chaves string posteriores sobrescrevem as anteriores.
• array_replace_recursive() — recursa como esta função, mas substitui valores em vez de coletá-los.
• array_combine() — constrói um array a partir de um array de chaves separado e um array de valores.

Conclusão

A função array_merge_recursive() é a escolha certa quando você deseja combinar valores sob chaves string compartilhadas em vez de sobrescrevê-los — agrupando, agregando ou acumulando dados entre arrays. Tenha em mente suas duas regras (chaves string se mesclam em listas, chaves inteiras são reindexadas) e escolha array_merge() ou array_replace_recursive() quando precisar de um comportamento de último-valor-prevalece.

Prática