PHP array_push(): agregar elementos a un array

array_push($arr, $value) añade un valor al final de un array. Para un solo valor, el atajo $arr[] = $value; hace lo mismo sin llamar a una función y es lo que usa la mayoría del código PHP. Los dos cambian el array en el sitio.

<?php
$colors = ['red', 'green'];

$colors[] = 'blue';                    // shorthand, one value
array_push($colors, 'yellow', 'pink'); // several values at once

print_r($colors);

array_push() recibe el array por referencia, así que modifica la variable que le pasas. Devuelve el nuevo número de elementos, que puedes ignorar.

array_push vs $arr[] =

Usa $arr[] = $value para un valor: es más corto y evita una llamada a función, algo que se nota dentro de un bucle grande. Usa array_push() cuando tengas varios valores que añadir en una sentencia, o una lista de valores que desplegar.

<?php
$log = [];
for ($i = 1; $i <= 3; $i++) {
    $log[] = "step $i";
}

$more = ['step 4', 'step 5'];
$count = array_push($log, ...$more);   // spread a list in

print_r($log);
echo "Now $count entries\n";

$arr[] = también funciona con una variable que aún no existe: PHP crea el array. array_push() necesita un array existente: con una variable no definida lanza TypeError: array_push(): Argument #1 ($array) must be of type array, null given.

Añadir una clave y un valor

array_push() solo añade valores con la siguiente clave entera. Para añadir una clave con nombre, asígnale el valor. Para añadir varios pares a la vez, usa += (conserva las claves existentes) o array_merge() (hace que ganen los valores nuevos).

<?php
$user = ['name' => 'Ada'];

$user['email'] = 'ada@example.com';             // one key and value
$user += ['role' => 'admin', 'name' => 'X'];    // adds role; name already exists, kept

print_r($user);

array_push($user, 'oops');                      // gets key 0, not a name
print_r($user);

La diferencia entre + y array_merge() cuando las claves coinciden se explica en la página de array_merge.

Añadir al principio: array_unshift

array_unshift($arr, $value) inserta al principio. Las claves enteras se renumeran para que el nuevo valor tenga el índice 0; las claves de texto se quedan como están. Igual que array_push(), acepta varios valores y devuelve el nuevo total.

<?php
$queue = ['Linus', 'Grace'];
array_unshift($queue, 'Ada');
print_r($queue);

$menu = ['home' => '/', 'about' => '/about'];
array_unshift($menu, '/login');      // string keys are kept, the new value gets key 0
print_r($menu);

Para poner primero un par con nombre, construye un array nuevo: $menu = ['login' => '/login'] + $menu;.

Insertar en una posición concreta

array_splice($arr, $offset, 0, $values) inserta sin eliminar nada: empieza en $offset, elimina 0 elementos y coloca ahí los valores nuevos. Las claves enteras posteriores al punto de inserción se renumeran.

<?php
$letters = ['a', 'b', 'd', 'e'];

array_splice($letters, 2, 0, 'c');           // insert 'c' at index 2
print_r($letters);

array_splice($letters, 1, 0, ['x', 'y']);    // insert two values at index 1
echo implode(' ', $letters), "\n";

array_splice() también puede eliminar y sustituir elementos; la página sobre eliminar elementos muestra esas formas.

Añadir otro array

array_push($a, $b) añade $b como un único elemento anidado, que rara vez es lo que quieres. Para añadir los valores de $b uno a uno, despliégalos, o construye un array nuevo con la sintaxis spread o array_merge().

<?php
$a = [1, 2];
$b = [3, 4];

$nested = $a;
array_push($nested, $b);       // [1, 2, [3, 4]]
echo json_encode($nested), "\n";

$flat = $a;
array_push($flat, ...$b);      // [1, 2, 3, 4]
echo json_encode($flat), "\n";

echo json_encode([...$a, ...$b]), "\n";

Error frecuente: asignar el valor de retorno

array_push() devuelve un número, el nuevo total de elementos. Volver a asignarlo a la variable del array sustituye tu array por un entero, y el siguiente array_push() sobre ella lanza un TypeError.

<?php
$items = ['pen', 'book'];

$result = array_push($items, 'lamp');
var_dump($result);    // the count, not the array

// Wrong: $items = array_push($items, 'mug');  turns $items into int(4)
array_push($items, 'mug');   // right: call it on its own line
print_r($items);

Lo mismo vale para array_unshift() y para sort(), que devuelve true. Las funciones que cambian un array en el sitio devuelven un estado, no el array.