array_key_first
Returns the first key of an array without moving the internal array pointer.
array_key_first(array $array): int|string|null- Added in PHP 7.3.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$array | array | An array. |
Return value
int|string|nullThe first key of the array, or null if the array is empty.
Errors
Passing a non-array argument throws a TypeError.
array_key_first() gives you the key of the first element in insertion order. "First" means first inserted, not lowest — [5 => 'a', 3 => 'b'] returns 5.
Why not reset()
Before PHP 7.3 the idiom was reset($array); $key = key($array);. That works but moves the array's internal pointer as a side effect, which quietly breaks any each()-style or current()-based iteration happening elsewhere. It also needs a variable, so it cannot be applied to a function's return value. array_key_first() has neither problem and reads better.
Empty arrays return null
There is no separate error signal, so null is ambiguous when your array legitimately contains the key null — except it cannot, since null keys are normalised to the empty string on insertion. In practice a null return always means the array was empty. Still, guard with if ($array === []) or count() before indexing with the result, otherwise you get an undefined array key warning.
Getting the value
PHP 8.5 added array_first(), which returns the first value directly. On older versions use $array[array_key_first($array)].
Example
When to use it
- Read the top entry of a sorted leaderboard without disturbing an ongoing iteration.
- Grab the first group name from a grouped result set to use as a default tab.
- Peek at the head of a queue array before deciding whether to shift it.
Frequently asked questions
What is the difference between array_key_first and reset?
reset() moves the array's internal pointer to the start and returns the first value, while array_key_first() returns the first key and leaves the pointer alone. Prefer array_key_first when you only want to look.
How do I get the first value rather than the first key?
Use $array[array_key_first($array)], or array_first($array) on PHP 8.5 and later. Guard against an empty array either way.
Does array_key_first return the lowest key?
No, it returns the key that was inserted first. For [5 => 'a', 3 => 'b'] it returns 5; sort the array by key with ksort() first if you want the lowest.
More examples
It does not touch the internal pointer
After next() the internal pointer sits on 'y'. array_key_first reports 'x' without moving it, so key() still returns 'y' — reset() would have rewound the pointer.
<?php
$a = ['x' => 1, 'y' => 2, 'z' => 3];
next($a);
echo 'pointer at: ', key($a), "\n";
echo 'first key: ', array_key_first($a), "\n";
echo 'pointer still at: ', key($a), "\n";Safely reading the first value
Checking for a null key before indexing avoids the undefined-key warning on an empty array. PHP 8.5's array_first() does the same job in one call.
<?php
function firstValue(array $a, mixed $fallback = null): mixed {
$key = array_key_first($a);
return $key === null ? $fallback : $a[$key];
}
var_dump(firstValue(['b' => 2, 'a' => 1]));
var_dump(firstValue([], 'empty'));
Discussion