PHP array_push(): adicionar elementos a um array

array_push($arr, $value) adiciona um valor ao fim de um array. Para um único valor, o atalho $arr[] = $value; faz o mesmo trabalho sem chamar função e é o que a maior parte do código PHP usa. Os dois alteram o array no lugar.

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

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

print_r($colors);

array_push() recebe o array por referência, então modifica a variável que você passa. Ele retorna o novo número de elementos, que você pode ignorar.

array_push ou $arr[] =

Use $arr[] = $value para um valor: é mais curto e evita uma chamada de função, o que faz diferença dentro de um loop grande. Use array_push() quando tiver vários valores para adicionar numa instrução, ou uma lista de valores para espalhar.

<?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[] = também funciona numa variável que ainda não existe: o PHP cria o array. O array_push() precisa de um array existente: numa variável indefinida ele lança TypeError: array_push(): Argument #1 ($array) must be of type array, null given.

Adicionar uma chave e um valor

O array_push() só acrescenta valores com a próxima chave inteira. Para adicionar uma chave com nome, atribua a ela. Para adicionar vários pares de uma vez, use += (mantém as chaves existentes) ou array_merge() (deixa os novos valores vencerem).

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

A diferença entre + e array_merge() quando as chaves colidem está na página sobre array_merge.

Adicionar no início: array_unshift

array_unshift($arr, $value) insere no começo. As chaves inteiras são renumeradas para que o novo valor receba o índice 0; chaves string continuam como estão. Como o array_push(), ele aceita vários valores e retorna a nova contagem.

<?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 colocar um par com nome primeiro, monte um novo array: $menu = ['login' => '/login'] + $menu;.

Inserir numa posição específica

array_splice($arr, $offset, 0, $values) insere sem remover nada: começa em $offset, remove 0 elementos e coloca os novos valores ali. As chaves inteiras depois do ponto de inserção são renumeradas.

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

O array_splice() também pode remover e substituir elementos; a página sobre remover elementos mostra essas formas.

Acrescentar outro array

array_push($a, $b) adiciona $b como um único elemento aninhado, o que raramente é o que você quer. Para adicionar os valores de $b um por um, espalhe-os, ou monte um novo array com a sintaxe spread ou 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";

Erro comum: atribuir o valor de retorno

O array_push() retorna um número, a nova contagem de elementos. Atribuir isso de volta à variável do array substitui o seu array por um inteiro, e o próximo array_push() nele lança um 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);

O mesmo vale para array_unshift() e para sort(), que retorna true. Funções que alteram um array no lugar devolvem um status, não o array.