Função array_push do PHP: Um Guia Completo

array_push() adiciona um ou mais elementos ao final de um array, tratando-o como uma pilha. É a maneira mais comum de expandir uma lista em PHP, e retorna o novo número de elementos após a adição dos valores.

Esta página aborda a sintaxe, o valor retornado por array_push(), o seu comportamento com arrays associativos e arrays vazios, o atalho [] mais rápido, e as funções relacionadas para remover ou adicionar elementos no início.

Sintaxe

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

• $array — o array a ser modificado. É passado por referência (&), portanto a variável original é alterada no lugar; não é necessário reatribuí-la.
• $values — um ou mais valores a serem adicionados, na ordem fornecida.
• Valor de retorno — o novo comprimento do array (um inteiro).

Exemplo básico

O exemplo abaixo começa com três frutas e adiciona mais duas:

Os novos valores são adicionados em ordem, e $count armazena o comprimento atualizado:

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

O atalho [] para um único valor

Se você precisar adicionar apenas um elemento, a sintaxe $array[] = $value faz a mesma coisa e é mais rápida, pois evita o custo de uma chamada de função:

<?php

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

?>

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

Use array_push() quando precisar adicionar vários valores de uma vez; use [] para um único valor.

Comportamento com chaves

array_push() sempre reindexará os valores adicionados com novas chaves inteiras, continuando a partir da maior chave inteira existente no array. As chaves string (associativas) existentes são mantidas intactas:

<?php

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

?>

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

Observe que o novo elemento tornou-se [6] — um após a maior chave inteira (5), e não [2].

Adicionando elementos a um array vazio

Não é necessário declarar chaves primeiro. Ao adicionar elementos a um array vazio, a numeração começa em 0:

<?php

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

?>

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

Erros comuns

• Modifica no lugar. Como o array é passado por referência, não escreva $arr = array_push($arr, $x) — isso substituiria seu array pelo comprimento inteiro. Chame array_push($arr, $x) em sua própria linha.
• O argumento deve ser uma variável. Como o parâmetro é por referência, não é possível usar um literal como array_push(array(), "x").
• Use [] para um valor. Para um único elemento, $arr[] = $value é mais claro e um pouco mais rápido.

Funções relacionadas

• array_pop() — remove e retorna o último elemento (o oposto de adicionar).
• array_unshift() — adiciona elementos ao início de um array.
• array_shift() — remove o primeiro elemento.
• array_merge() — combina dois ou mais arrays em um.
• array_splice() — insere ou remove elementos em qualquer posição.

Prática