array_first
Returns the first value of an array without moving the internal pointer, or null if the array is empty.
array_first(array $array): mixed- Added in PHP 8.5
Parameters
| Parameter | Type | Description |
|---|---|---|
$array | array | An array. |
Return value
mixedThe first value of array if the array is not empty; null otherwise.
Errors
Throws a TypeError if the argument is not an array.
array_first() returns the value stored at the array's first position — first in insertion order, not in key order. It is exactly $array[array_key_first($array)], with an empty-array check folded in, and it returns null when the array has no elements.
It exists because every earlier option had a catch. $array[0] assumes the array is a list with an intact key 0, which stops being true the moment you run array_filter() or unset(). reset($array) works but needs a variable (you cannot pass a function's return value to it without a notice) and it moves the internal array pointer as a side effect. current() depends on wherever the pointer happens to be.
Pointer-safe
array_first() takes its argument by value and does not touch the internal pointer. Code that mixes next(), current() and each()-style iteration will not be disturbed by it — but that also means it is not a drop-in replacement for reset() if the surrounding code was relying on the rewind.
Example
When to use it
- Read the first row of a query result that was keyed by id rather than numbered.
- Grab the first surviving element after array_filter() has punched holes in the keys.
- Take the highest-priority entry from a sorted associative config array.
Frequently asked questions
What is the difference between array_first and reset?
reset() rewinds the internal array pointer and returns the first value, so it mutates state and needs a variable argument. array_first() just reads the first value, leaves the pointer alone, and accepts any array expression.
Does array_first work on associative arrays?
Yes. It returns the value at the first insertion position regardless of what the keys are, so it works identically for lists and string-keyed arrays.
What does array_first return for an empty array?
null, with no warning. It also returns null when the first value is genuinely null, so use array_key_first() or an empty() check if you need to tell those cases apart.
More examples
Why $array[0] is not enough
array_filter() preserves keys, so $odd has keys 1 and 4 and no key 0 at all. array_first() still returns int(15) and array_last() int(41), while $odd[0] falls through to the default string.
<?php
$rows = [10, 15, 22, 30, 41];
$odd = array_filter($rows, fn(int $n) => $n % 2 === 1);
print_r($odd);
var_dump(array_first($odd));
var_dump(array_last($odd));
var_dump($odd[0] ?? 'no key 0');Polyfill for PHP below 8.5
On PHP 8.5 the guard is false and the built-in is used; on older versions the shim takes over with identical behaviour. It prints string(1) "/" and then the matching key string(4) "home".
<?php
if (!function_exists('array_first')) {
function array_first(array $array): mixed {
return $array ? $array[array_key_first($array)] : null;
}
}
$menu = ['home' => '/', 'docs' => '/docs', 'blog' => '/blog'];
var_dump(array_first($menu));
var_dump(array_key_first($menu));
Discussion