Función array_push de PHP: Guía completa

array_push() añade uno o más elementos al final de un array, tratándolo como una pila. Es la forma habitual de ampliar una lista en PHP, y devuelve el nuevo número de elementos una vez que los valores han sido añadidos.

Esta página cubre la sintaxis, el valor que devuelve array_push(), su comportamiento con arrays asociativos y vacíos, el atajo [] más rápido, y las funciones relacionadas para eliminar o anteponer elementos.

Sintaxis

array_push(array &$array, mixed ...$values): int

• $array — el array a modificar. Se pasa por referencia (&), por lo que la variable original se modifica en el lugar; no es necesario reasignarla.
• $values — uno o más valores a añadir al final, en el orden indicado.
• Valor de retorno — la nueva longitud del array (un entero).

Ejemplo básico

El siguiente ejemplo comienza con tres frutas y añade dos más:

Los nuevos valores se añaden en orden y $count contiene la longitud actualizada:

5
Array
(
    [0] => apple
    [1] => banana
    [2] => cherry
    [3] => orange
    [4] => peach
)

El atajo [] para un solo valor

Si solo necesitas añadir un elemento, la sintaxis $array[] = $value hace lo mismo y es más rápida, porque evita la sobrecarga de una llamada a función:

<?php

$colors = array("red", "green");
$colors[] = "blue"; // same as array_push($colors, "blue")
print_r($colors);

?>

Array
(
    [0] => red
    [1] => green
    [2] => blue
)

Usa array_push() cuando necesites añadir varios valores a la vez; utiliza [] para un solo valor.

Comportamiento con claves

array_push() siempre reindexa los valores añadidos con nuevas claves enteras, continuando desde la clave entera más alta existente en el array. Las claves de cadena (asociativas) existentes no se modifican:

<?php

$data = array("name" => "Ann", 5 => "five");
array_push($data, "added");
print_r($data);

?>

Array
(
    [name] => Ann
    [5] => five
    [6] => added
)

Observa que el nuevo elemento se convirtió en [6] — uno más que la clave entera más grande (5), no [2].

Insertar en un array vacío

No es necesario declarar claves de antemano. Insertar en un array vacío comienza la numeración en 0:

<?php

$list = array();
array_push($list, "first", "second");
print_r($list);

?>

Array
(
    [0] => first
    [1] => second
)

Errores comunes

• Modifica en el lugar. Como el array se pasa por referencia, no escribas $arr = array_push($arr, $x) — eso sobrescribiría tu array con la longitud entera. Llama a array_push($arr, $x) en su propia línea.
• El argumento debe ser una variable. Como el parámetro es por referencia, no puedes insertar en un literal como array_push(array(), "x").
• Usa [] para un valor. Para un solo elemento, $arr[] = $value es más claro y un poco más rápido.

Funciones relacionadas

• array_pop() — elimina y devuelve el último elemento (lo contrario de insertar).
• array_unshift() — añade elementos al principio de un array.
• array_shift() — elimina el primer elemento.
• array_merge() — combina dos o más arrays en uno.
• array_splice() — inserta o elimina elementos en cualquier posición.

Práctica