array_push()

Purpose

array_push() adds one or more values to the end of an array. It treats the array like a stack: each value you pass is placed after the current last element, and the array grows by the number of values you supplied. The effect is the same as writing $array[] = $value; once per value.

The function changes the original variable. It does not return a new array, which is a frequent source of confusion for people used to functions that return a modified copy.

Signature

Parameters and defaults

• $array is the array to modify. It is taken by reference, so you must pass a variable. A literal array or a function result cannot be used here.
• ...$values is a variadic list of values to append. There is no default value. Since PHP 7.3 you may pass zero values, in which case the array stays unchanged.

Values are appended in the order you pass them. Each one can be of any type, including another array or an object.

Return value and failure cases

The function returns the new number of elements in the array as an integer. It does not return the array and does not return the pushed value.

In PHP 8 the first parameter is declared as array, so passing something that is not an array, such as null or a string, raises a TypeError. Older documentation describes a warning, but the declared type is what applies in current PHP. A rarer failure happens when the array already uses the largest possible integer key, because there is no next index to assign. PHP then throws an Error instead of appending.

Example 1: basic push and return value

The first example appends two values and prints the returned count along with the final array.

<?php
$stack = ["orange", "banana"];
$count = array_push($stack, "apple", "raspberry");
echo $count, "\n";
echo json_encode($stack, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

4
["orange","banana","apple","raspberry"]

Example 2: how keys are assigned

Pushed values always receive new integer keys, continuing after the largest existing integer key. String keys are left alone and existing keys are never renumbered.

<?php
$data = [5 => "a", "name" => "x"];
array_push($data, "b", "c");
echo json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

{"5":"a","name":"x","6":"b","7":"c"}

Here the next integer key after 5 is 6, then 7. The string key name keeps its place.

Example 3: spreading arrays versus pushing an array

To append every item of another array, unpack it with the spread operator. If you pass the array itself, it becomes one nested element.

<?php
$queue = [1];
$more = [2, 3];
array_push($queue, ...$more);
array_push($queue, [4, 5]);
echo count($queue), "\n";
echo json_encode($queue, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

4
[1,2,3,[4,5]]

The first call adds two elements. The second adds a single element that happens to be an array, so the final count is 4.

Edge cases

• Empty array: pushing onto [] starts at key 0.
• No values: calling array_push($list) with only the array is allowed and returns the current count.
• Negative keys: the next key is based on the largest existing integer key, so behavior with negative-only keys follows the normal append rules of the language rather than any special handling in array_push().
• References: the array is passed by reference, so every other variable that references the same array sees the change. Ordinary copies made earlier are not affected.
• Not a queue insert: values only go at the end. To add at the start use array_unshift().

Common mistakes

1. Assigning the result to the array. Writing $list = array_push($list, 1); replaces the array with an integer count. Call the function on its own line and use the return value only if you need the size.
2. Passing a non-variable. Because of the by-reference parameter, array_push(getItems(), 1) is an error. Store the result in a variable first.
3. Expecting merging. Pushing an array adds it as one element. Use the spread operator or array_merge() when you want a flat result.
4. Using it for a single value in hot code. For one element, $array[] = $value; does the same job without a function call, and the manual recommends it for that reason. array_push() is most useful when you push several values at once, spread a list, or need the new count.
5. Assuming string keys can be set. You cannot choose keys with array_push(). Use $array['key'] = $value; for that.

Related functions

• array_pop() removes and returns the last element.
• array_shift() removes and returns the first element.
• array_unshift() prepends one or more elements.
• array_merge() combines arrays and returns a new one.

Recap

array_push() appends values to a referenced array, assigns new integer keys after the highest existing one, and returns the new element count. Use $array[] = for a single value, spread an array to append its items, and never assign the integer result back to the array variable.