array_shift
Removes the first element of an array, returns it, and reindexes the remaining numeric keys.
array_shift(array &$array): mixed- Added in PHP 4.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$array | array | The input array, passed by reference. It is modified in place: the first element is removed and remaining integer keys are renumbered from 0. |
Return value
mixedThe value that was removed from the front of the array, or null if the array is empty.
Errors
Throws a TypeError if the argument is not an array or is not a variable that can be passed by reference.
array_shift() takes the first element off an array, hands it back to you, and shrinks the array by one. Because the array is taken by reference, you must pass a variable — you cannot shift a function's return value directly.
When to reach for it
It is the dequeue half of a FIFO queue: push work on the end with array_push() or [], take it off the front with array_shift(). It is also handy for peeling a header row off parsed CSV data, or for consuming a list of command arguments one at a time.
What trips people up
Every remaining integer key is renumbered from zero. String keys are left alone, but any numeric keys you were relying on are gone. That renumbering also means the call is O(n), not O(1): shifting through a large array in a loop is quadratic. For big queues, iterate with foreach, or keep an index and read $queue[$i++].
An empty array returns null, and so does an array whose first value genuinely is null. If your data can contain nulls, test with count() or $array === [] instead of checking the return value.
Example
When to use it
- Consume a job queue one item at a time until it is empty.
- Pull the header row off a parsed CSV before mapping the remaining rows.
- Read positional arguments from a list where each step removes the one it just handled.
Frequently asked questions
What is the difference between array_shift and array_pop?
array_shift removes the first element and renumbers the remaining integer keys; array_pop removes the last element and leaves the other keys alone. array_pop is O(1), array_shift is O(n).
Why did my array keys change after array_shift?
array_shift reindexes all integer keys starting at 0 so the result stays a proper list. Use array_slice($array, 1, null, true) if you need the original keys preserved.
How do I tell an empty array from a null value with array_shift?
Check the array first with $array === [] or count($array), because array_shift returns null both when the array is empty and when the first element is itself null.
More examples
Keys are renumbered
Prints a, then the remaining array as [0 => 'b', 'x' => 'c']. The integer key 9 became 0, while the string key 'x' was left untouched.
<?php
$rows = [5 => 'a', 9 => 'b', 'x' => 'c'];
$first = array_shift($rows);
echo $first, "\n";
print_r($rows);Splitting a header off CSV data
array_shift removes the header row and returns it, leaving $rows with only data. array_combine then turns each remaining row into an associative record keyed by the header names.
<?php
$rows = [
['id', 'name'],
['1', 'Widget'],
['2', 'Gadget'],
];
$header = array_shift($rows);
foreach ($rows as $row) {
print_r(array_combine($header, $row));
}Null is ambiguous
The first and third calls both return NULL for completely different reasons. This is why an emptiness check on the array itself is safer than testing the returned value.
<?php
$items = [null, 'b'];
var_dump(array_shift($items)); // NULL - a real value
var_dump(array_shift($items)); // string(1) "b"
var_dump(array_shift($items)); // NULL - array was empty
var_dump($items);
Discussion