PHP array_merge(): unir dos o más arrays

array_merge($a, $b) devuelve un array nuevo con los elementos de $a seguidos de los de $b. Las claves numéricas se renumeran desde 0; cuando los dos arrays tienen la misma clave de texto, gana el valor del array posterior. Puedes pasar tantos arrays como quieras.

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

array_merge() no cambia sus argumentos. Devuelve el array combinado, así que asigna el resultado: $all = array_merge($all, $more);.

Las claves numéricas se renumeran

array_merge() trata las claves enteras como posiciones, no como nombres. Cada elemento con clave entera se añade al final y recibe una clave nueva desde 0, aunque los arrays usaran los mismos números o tuvieran huecos. Es lo que quieres con listas, y una sorpresa cuando los números son 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

Las claves de texto que parecen enteros ('101') se guardan como enteros, así que también se renumeran. Las claves como 'id101' se quedan como están.

array_merge vs el operador +

El operador + (unión de arrays) también combina arrays, pero con la regla contraria: para cualquier clave que ya exista en el array izquierdo, gana el valor izquierdo y el derecho se descarta. Nunca renumera. Eso hace de + la forma natural de rellenar valores por defecto, y de array_merge() la forma natural de sobrescribirlos.

<?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']);

El último ejemplo del bloque es la trampa clásica de +: ['a', 'b'] + ['x', 'y', 'z'] da a, b, z, porque las claves 0 y 1 ya existen a la izquierda.

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

El operador spread despliega arrays dentro de un literal de array. Se comporta como array_merge(): las claves enteras se renumeran y, desde PHP 8.1, se permiten claves de texto y gana la posterior. Se lee bien cuando mezclas arrays con valores sueltos.

<?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 añadir un array a uno existente en el sitio, consulta array_push() con el operador spread.

Unir un array de arrays

Cuando los arrays que quieres combinar están a su vez en una lista, despliega esa lista en array_merge(). Es también la forma rápida de unir dentro de un bucle: reúne las piezas y únelas una sola 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 []

Escribir $all = array_merge($all, $batch); dentro del bucle funciona, pero copia todo el array creciente en cada vuelta, lo que se vuelve lento con miles de elementos.

array_merge_recursive y array_replace

array_merge_recursive() también une los arrays anidados, pero con una clave de texto duplicada que contiene valores simples no sobrescribe: reúne los dos valores en un array nuevo. Rara vez es lo que quieres para una configuración. Ahí la herramienta adecuada suele ser array_replace_recursive(): sobrescribe los valores en todos los niveles y conserva las claves.

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

Lee las tres líneas de JSON de arriba abajo: array_merge() sustituyó todo el array db y perdió host, array_merge_recursive() convirtió port y debug en listas de dos elementos, y array_replace_recursive() produjo la configuración que querías.

Error frecuente: unir no elimina nada

array_merge() conserva los valores duplicados que están bajo claves distintas. Unir dos listas de etiquetas te da dos veces cada etiqueta compartida. Pasa el resultado por array_unique() y luego por array_values() para renumerarlo.

<?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";

La página de array_unique explica cómo quitar duplicados de filas y arrays anidados.