array_unshift()

Purpose

array_unshift() puts one or more values at the start of an array. It is the front-of-the-array counterpart to array_push(), which adds to the end. The function changes the array you give it, so it is useful for queues where urgent items jump ahead, for history lists where the newest entry comes first, and for adding a default option at the top of a list.

Signature

Parameters and defaults

• $array: the input array. It is passed by reference, so the original variable is modified. Because of this, you must pass a variable, not a literal or a function result.
• ...$values: zero or more values to prepend. There is no default value. The values are prepended as a group and keep the order you wrote them in. Calling array_unshift($a, 1, 2) gives 1, 2, ..., not 2, 1, ....

The manual's changelog says the function can be called with only one argument since PHP 7.3.0. With no values, the array stays as it is, apart from the effects described below.

Return value and failure cases

The function returns an int: the new number of elements in the array. It does not return the array itself.

If the first argument is not an array, PHP throws a TypeError. If you pass something that cannot be a reference, such as a literal array, PHP raises an Error, because the argument cannot be passed by reference.

Key behavior

Existing numeric keys are renumbered to start at zero, while string keys are kept. The prepended values get the first numeric keys. The manual also notes that the array's internal pointer is reset to the first element.

Example 1: prepending several values

The two new values land at the front in the order given, and the return value is the new length.

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

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

Example 2: numeric keys are renumbered, string keys stay

The original keys 5 and 9 do not survive. The string key name is untouched. Because the result is no longer a plain list, json_encode() writes it as an object.

<?php
$data = [5 => "five", "name" => "Ada", 9 => "nine"];
$count = array_unshift($data, "first");
echo $count, "\n";
echo json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

4
{"0":"first","1":"five","name":"Ada","2":"nine"}

Example 3: one array versus spread values

An array passed as a value becomes a single nested element. If you want to prepend each item separately, spread it with .... With no values at all, the function just reports the current count.

<?php
$stack = ["b", "c"];
array_unshift($stack, ["x", "y"]);
echo json_encode($stack, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

$items = ["b", "c"];
array_unshift($items, ...["x", "y"]);
echo json_encode($items, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

$same = [1, 2];
echo array_unshift($same), "\n";

[["x","y"],"b","c"]
["x","y","b","c"]
2

Edge cases

• Empty array: prepending to [] simply creates a list holding the new values, and the return value is the number of values you passed.
• Nested arrays: a prepended array is not merged. It is inserted as one element, as Example 3 shows. The manual's associative example demonstrates the same thing: an associative array prepended to another becomes element 0.
• Numeric string keys: keys such as "7" are treated as integer keys by PHP, so they are renumbered too.
• Cost: every existing numeric element has to be renumbered, so using it repeatedly on very large arrays does more work than appending with array_push() or [].

Common mistakes

1. Assigning the result to the array. Writing $list = array_unshift($list, "x"); replaces your array with an integer. Call the function on its own line and use the return value only if you need the count.
2. Expecting reversed order. Several values are prepended together, in their written order. Only a loop that prepends one value at a time would reverse them.
3. Expecting original numeric keys to survive. If keys carry meaning, such as IDs, renumbering will break lookups. Use a string key strategy or build a new array with the + operator or array_merge() instead.
4. Passing a non-variable. A literal or a function call result cannot be modified by reference. Store it in a variable first.
5. Forgetting that an array argument nests. Use the spread operator when you want each item added individually.

If you need a non-mutating version, build a new array with array_merge([$first], $rest) and leave the original untouched.

Related functions

• array_shift() removes and returns the first element.
• array_push() appends one or more elements to the end.
• array_pop() removes and returns the last element.
• array_merge() combines arrays into a new array without modifying the inputs.

Recap

array_unshift() modifies an array in place by adding values at the front, keeps their given order, renumbers numeric keys, preserves string keys and returns the new element count. Remember that it returns an integer rather than an array, and that an array passed as a value is added as one nested element.