array_unshift
Prepends one or more values to the front of an array and returns the new element count.
array_unshift(array &$array, mixed ...$values): int- Added in PHP 4.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$array | array | The input array, passed by reference and modified in place. |
$valuesoptional | mixed | One or more values to prepend. They are inserted as a block, keeping their relative order. Variadic. |
Return value
intThe new number of elements in the array.
Errors
Throws a TypeError if the first argument is not a referenceable array variable.
Changelog
- PHP 7.3The function can now be called with only one parameter. Previously at least two parameters were required.
array_unshift() pushes values onto the front of an array. The array is passed by reference and modified in place; the return value is the new count, not the array.
When to reach for it
Use it to put a default option at the top of a select list, to add a root crumb to a breadcrumb trail, or to prepend the most recent item to a capped list. Multiple values are inserted in one call and keep their order, so array_unshift($a, 'x', 'y') puts x before y before the rest — not reversed, which surprises people expecting a repeated single-value push.
What trips people up
All integer keys are renumbered from zero. String keys are preserved, but any array keyed by database id will silently lose those ids. Use ['new' => $v] + $array (the union operator) or array_merge() when keys matter.
Assigning the return value is the classic mistake: $a = array_unshift($a, 'x') replaces your array with an integer. The modified array stays in the variable you passed.
Prepending is O(n) because everything shifts. Building a list by unshifting in a loop is quadratic — append with $a[] = and call array_reverse() once at the end.
Example
When to use it
- Put a "— select —" placeholder at the top of a dropdown options array.
- Add the site root to the front of a breadcrumb trail built from the leaf upwards.
- Prepend the newest entry to a recently-viewed list before trimming it to a fixed length.
Frequently asked questions
What is the difference between array_unshift and array_push?
array_unshift adds elements to the beginning of the array and renumbers the integer keys; array_push adds them to the end and leaves existing keys alone.
Does array_unshift return the modified array?
No, it returns the new element count as an integer. The array itself is modified in place because it is passed by reference.
How do I prepend to an array without losing the keys?
Use the union operator: $result = ['key' => $value] + $array. It keeps every original key, unlike array_unshift which renumbers integer keys from 0.
More examples
Integer keys are renumbered
The result is [0 => 'first', 'x' => 1, 1 => 'five']. The string key 'x' is untouched but the integer key 5 was renumbered to 1, which is why array_unshift is unsafe on id-keyed data.
<?php
$mixed = ['x' => 1, 5 => 'five'];
array_unshift($mixed, 'first');
print_r($mixed);Prepending without losing keys
The union operator keeps 7 and 3 intact while adding the new entry at the front. array_unshift renumbers them to 1 and 2, showing the difference in one run.
<?php
$byId = [7 => 'alice', 3 => 'bob'];
$withDefault = ['none' => '(unassigned)'] + $byId;
print_r($withDefault);
$copy = $byId;
array_unshift($copy, '(unassigned)');
print_r($copy);Building a capped recent list
The new page goes to the front and array_splice trims everything from index 3 onward, leaving page-4, page-3, page-2. This is the usual pattern for a fixed-size most-recently-used list.
<?php
$recent = ['page-3', 'page-2', 'page-1'];
array_unshift($recent, 'page-4');
array_splice($recent, 3); // keep only the newest three
print_r($recent);
echo count($recent), " kept\n";
Discussion