PHP array_push(): Add Elements to an Array

array_push($arr, $value) adds a value to the end of an array. For a single value, the shorthand $arr[] = $value; does the same job without a function call and is what most PHP code uses. Both change the array in place.

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

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

print_r($colors);

array_push() takes the array by reference, so it modifies the variable you pass. It returns the new number of elements, which you can ignore.

array_push vs $arr[] =

Use $arr[] = $value for one value: it is shorter and avoids a function call, which adds up inside a big loop. Use array_push() when you have several values to add in one statement, or a list of values to spread in.

<?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[] = also works on a variable that does not exist yet: PHP creates the array. array_push() needs an existing array: on an undefined variable it throws TypeError: array_push(): Argument #1 ($array) must be of type array, null given.

Add a key and value

array_push() only appends values with the next integer key. To add a named key, assign to it. To add several pairs at once, use += (keeps existing keys) or array_merge() (lets the new values win).

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

The difference between + and array_merge() when keys collide is covered on the array_merge page.

Add to the beginning: array_unshift

array_unshift($arr, $value) inserts at the start. Integer keys are renumbered so the new value gets index 0; string keys stay as they are. Like array_push(), it accepts several values and returns the new count.

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

To put a named pair first, build a new array: $menu = ['login' => '/login'] + $menu;.

Insert at a specific position

array_splice($arr, $offset, 0, $values) inserts without removing anything: it starts at $offset, removes 0 elements, and puts the new values there. The integer keys after the insertion point are renumbered.

<?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() can also remove and replace elements; the page on removing elements shows those forms.

Append another array

array_push($a, $b) adds $b as one nested element, which is rarely what you want. To add the values of $b one by one, spread them, or build a new array with the spread syntax or 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";

Common mistake: assigning the return value

array_push() returns a number, the new element count. Assigning that back to the array variable replaces your array with an integer, and the next array_push() on it throws a 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);

The same applies to array_unshift() and to sort(), which returns true. Functions that change an array in place give back a status, not the array.