PHP Array Merge: Um Guia Completo

A função PHP array_merge() combina dois ou mais arrays em um único array. Ela recebe um ou mais arrays como argumentos e retorna um novo array; os arrays originais permanecem inalterados. Este guia aborda como array_merge() trata chaves string, chaves numéricas e arrays aninhados, as armadilhas a observar e como ela difere do operador de união +.

As duas regras que explicam quase todos os resultados são:

• Chaves string que aparecem em mais de um array são sobrescritas — o valor do array posterior prevalece.
• Chaves numéricas nunca são sobrescritas. Cada valor é acrescentado ao final e as chaves são reindexadas sequencialmente a partir de 0.

Nota: A partir do PHP 8.0, passar um argumento que não seja um array para array_merge() lança um TypeError. (No PHP 7, isso gerava um aviso e retornava null.) Chamar array_merge() sem argumentos retorna um array vazio.

Uso Básico de array_merge()

O uso básico da função array_merge() é simples. Basta passar dois ou mais arrays como argumentos, e a função retornará um novo array resultado da fusão dos arrays. Veja um exemplo:

Exemplo da função array_merge em PHP

Saída:

Array
(
    [color] => green
    [0] => 2
    [1] => 4
    [2] => a
    [3] => b
    [shape] => rectangle
    [4] => 4
)

Observe dois pontos na saída:

• A chave string color existe em ambos os arrays, então o valor de $array2 (green) sobrescreveu o valor de $array1 (red).
• As chaves numéricas não foram preservadas. Os valores originais 2 e 4 de $array1 e o 4 de $array2 foram todos mantidos (nenhum foi sobrescrito) e renumerados como 0, 1, 4.

Reindexação de Chaves Numéricas

Como as chaves numéricas são renumeradas, não é possível depender da preservação dos índices inteiros originais após uma fusão. Até mesmo chamar array_merge() em um único array é uma forma comum e rápida de reindexá-lo:

<?php

$nums = [10 => "a", 25 => "b", 7 => "c"];
$result = array_merge($nums);
print_r($result);

?>

Saída:

Array
(
    [0] => a
    [1] => b
    [2] => c
)

Se você precisar manter chaves inteiras específicas, use o operador de união + ou array_replace().

Mesclando Arrays Multidimensionais

A função array_merge() também pode ser usada para mesclar arrays multidimensionais. Para isso, basta passar cada array como argumento para a função. Veja um exemplo:

PHP para mesclar arrays multidimensionais usando array_merge_recursive

Saída:

Array
(
    [color] => Array
        (
            [favorite] => green
        )
    [0] => 2
    [1] => 4
    [2] => a
    [3] => b
    [shape] => rectangle
    [4] => 4
)

Observe que array_merge() não mescla arrays aninhados. Quando dois arrays compartilham uma chave string cujo valor é em si um array, o valor aninhado do array posterior substitui completamente o anterior — aqui ["favorite" => "green"] simplesmente sobrescreveu ["favorite" => "red"]. Para mesclar arrays aninhados recursivamente em vez de sobrescrevê-los, use array_merge_recursive().

array_merge() vs o Operador de União

PHP também oferece o operador de união + para combinar arrays, mas ele se comporta de forma muito diferente de array_merge(). O operador de união mantém o valor do operando da esquerda quando há colisão de chaves, e nunca reindexará as chaves numéricas.

<?php

$array1 = ["a", "b", "c"];
$array2 = ["x", "y", "z", "w"];

print_r(array_merge($array1, $array2)); // appends + reindexes
print_r($array1 + $array2);             // keeps left, no reindex

?>

Saída:

Array
(
    [0] => a
    [1] => b
    [2] => c
    [3] => x
    [4] => y
    [5] => z
    [6] => w
)
Array
(
    [0] => a
    [1] => b
    [2] => c
    [3] => w
)

Com array_merge(), todos os elementos são mantidos e renumerados. Com +, os índices 0–2 já existiam em $array1 e por isso prevalecem, e apenas o índice 3 (w) é incorporado de $array2. Use + quando quiser preencher chaves ausentes (como ao mesclar opções do usuário sobre valores padrão) preservando os valores e chaves inteiras existentes; use array_merge() quando quiser uma lista plana com indexação sequencial. Consulte Operadores PHP para mais informações.

Mesclando um Array Indexado com um Array Associativo

Ao mesclar um array indexado com um array associativo, os valores de ambos os arrays são combinados. Veja um exemplo:

Exemplo PHP de mesclagem de um array indexado com um array associativo pela função array_merge

Saída:

Array
(
    [0] => a
    [1] => b
    [2] => c
    [a] => apple
    [b] => banana
    [c] => cherry
)

Como você pode ver, os valores de ambos os arrays são combinados. Como as chaves são de tipos diferentes (numérico vs. string), não há sobrescrita. Este é um detalhe importante a ter em mente ao mesclar arrays com tipos de chave distintos.

Mesclando um Array Associativo com um Array Indexado

O resultado de mesclar um array associativo com um array indexado é similar. Os valores são combinados e as chaves são preservadas de acordo com seu tipo. Veja um exemplo:

PHP mesclando um array associativo com um array indexado usando a função array_merge

Saída:

Array
(
    [a] => apple
    [b] => banana
    [c] => cherry
    [0] => a
    [1] => b
    [2] => c
)

Como mostrado, os valores se combinam sem conflito. As chaves string de $array1 são preservadas, enquanto as chaves numéricas de $array2 são reindexadas a partir de 0.

Considerações de Desempenho

A função array_merge() tem complexidade de tempo linear, o que significa que o tempo necessário para mesclar arrays aumenta linearmente com o tamanho dos arrays. Por essa razão, é importante minimizar o número de arrays sendo mesclados e evitar o uso da função em arrays extremamente grandes.

Conclusão

A função array_merge() é uma ferramenta versátil para combinar arrays em PHP. Lembre-se das duas regras principais: chaves string são sobrescritas pelos arrays posteriores, enquanto chaves numéricas são acrescentadas ao final e reindexadas a partir de 0. Quando esses comportamentos padrão não se adequam ao seu caso, escolha uma função relacionada:

• array_merge_recursive() — mescla arrays aninhados em vez de sobrescrevê-los.
• array_replace() — substitui valores por chave preservando as chaves numéricas.
• O operador de união + — mantém os valores do lado esquerdo e nunca reindexará.
• array_combine() — constrói um array a partir de um array de chaves e um array de valores separados.

Prática