PHP array_merge(): juntar dois ou mais arrays

array_merge($a, $b) retorna um novo array com os elementos de $a seguidos dos elementos de $b. Chaves numéricas são renumeradas a partir de 0; quando os dois arrays têm a mesma chave string, o valor do array posterior vence. Passe quantos arrays quiser.

<?php
$fruits = ['apple', 'pear'];
$veg    = ['carrot', 'leek'];
print_r(array_merge($fruits, $veg));

$defaults = ['color' => 'blue', 'size' => 'M'];
$chosen   = ['size' => 'L'];
print_r(array_merge($defaults, $chosen));   // later value wins

O array_merge() não altera os argumentos. Ele retorna o array combinado, então atribua o resultado: $all = array_merge($all, $more);.

Chaves numéricas são renumeradas

O array_merge() trata chaves inteiras como posições, não como nomes. Todo elemento com chave inteira é acrescentado e recebe uma nova chave a partir de 0, mesmo que os arrays usassem os mesmos números ou tivessem buracos. É o que você quer para listas, e uma surpresa quando os números são IDs.

<?php
$a = [5 => 'Ada', 9 => 'Linus'];
$b = [5 => 'Grace'];

print_r(array_merge($a, $b));   // keys 0, 1, 2: the IDs are gone

$usersById = [101 => 'Ada', 102 => 'Linus'];
$more      = [103 => 'Grace'];
print_r($usersById + $more);    // + keeps the integer keys

Chaves string que parecem inteiros ('101') são guardadas como inteiros, então também são renumeradas. Chaves como 'id101' continuam como estão.

array_merge ou o operador +

O operador + (união de arrays) também combina arrays, mas com a regra oposta: para qualquer chave que já existe no array da esquerda, o valor da esquerda vence e o da direita é descartado. Ele nunca renumera. Isso faz do + o jeito natural de preencher padrões, e do array_merge() o jeito natural de sobrescrevê-los.

<?php
$defaults = ['theme' => 'light', 'lang' => 'en', 'per_page' => 20];
$user     = ['theme' => 'dark'];

print_r(array_merge($defaults, $user));   // user overrides defaults
print_r($user + $defaults);               // same result: user is on the left

// With lists, + compares positions and drops duplicates by key
print_r(['a', 'b'] + ['x', 'y', 'z']);

O último exemplo do bloco é a armadilha clássica do +: ['a', 'b'] + ['x', 'y', 'z'] dá a, b, z, porque as chaves 0 e 1 já existem à esquerda.

Sintaxe spread: [...$a, ...$b]

O operador spread desempacota arrays dentro de um literal de array. Ele se comporta como o array_merge(): chaves inteiras são renumeradas e, desde o PHP 8.1, chaves string são permitidas e a posterior vence. Fica legível quando você mistura arrays com valores avulsos.

<?php
$first  = [1, 2];
$second = [3, 4];

print_r([...$first, ...$second, 5]);

$base  = ['host' => 'localhost', 'port' => 3306];
$local = ['port' => 3307];
print_r([...$base, ...$local]);

Para acrescentar um array a outro existente no lugar, veja array_push() com o operador spread.

Juntar um array de arrays

Quando os arrays a combinar estão eles mesmos numa lista, espalhe essa lista no array_merge(). Esse também é o jeito rápido de juntar dentro de um loop: reúna as partes e faça o merge uma vez.

<?php
$pages = [
    ['ada', 'linus'],
    ['grace'],
    ['margaret', 'alan'],
];

$all = array_merge(...$pages);
print_r($all);

$batches = [];
for ($page = 1; $page <= 3; $page++) {
    $batches[] = range($page * 10, $page * 10 + 2);   // pretend API page
}
echo implode(', ', array_merge(...$batches)), "\n";

var_dump(array_merge(...[]));   // an empty list gives []

Escrever $all = array_merge($all, $batch); dentro do loop funciona, mas copia o array crescente inteiro a cada volta, o que fica lento com milhares de itens.

array_merge_recursive e array_replace

O array_merge_recursive() também junta arrays aninhados, mas para uma chave string repetida com valores simples ele não sobrescreve: junta os dois valores num novo array. Raramente é o que você quer para configuração. O array_replace_recursive() costuma ser a ferramenta certa ali: ele sobrescreve valores em todos os níveis e mantém as chaves.

<?php
$defaults = ['db' => ['host' => 'localhost', 'port' => 3306], 'debug' => false];
$override = ['db' => ['port' => 3307], 'debug' => true];

echo json_encode(array_merge($defaults, $override)), "\n";
echo json_encode(array_merge_recursive($defaults, $override)), "\n";
echo json_encode(array_replace_recursive($defaults, $override)), "\n";

print_r(array_replace([5 => 'a', 9 => 'b'], [9 => 'B']));   // keeps integer keys

Leia as três linhas de JSON de cima para baixo: o array_merge() substituiu o array db inteiro e perdeu host, o array_merge_recursive() transformou port e debug em listas de dois elementos, e o array_replace_recursive() produziu a configuração que você queria.

Erro comum: o merge não remove nada

O array_merge() mantém valores repetidos que estão sob chaves diferentes. Juntar duas listas de tags dá cada tag em comum duas vezes. Passe o resultado por array_unique() e depois por array_values() para renumerar.

<?php
$postTags  = ['php', 'arrays', 'beginner'];
$extraTags = ['arrays', 'tutorial', 'php'];

$merged = array_merge($postTags, $extraTags);
echo implode(', ', $merged), "\n";

$unique = array_values(array_unique($merged));
echo implode(', ', $unique), "\n";

A página sobre array_unique explica como remover duplicados de linhas e de arrays aninhados.