key()

Introduction

Every PHP array keeps an internal pointer that marks one element as the "current" one. The key() function reads the key (not the value) of whatever element that pointer is on. It is the partner of current(), which returns the value at the same position, and it is most often used together with next() and prev() to walk an array manually. This chapter explains what key() returns, how the internal pointer moves, the edge cases that return null, and the practical patterns where key() is genuinely useful.

Understanding the key() function

key() returns the key of the element that the array's internal pointer currently points at. It does not advance the pointer — it only reads the current position. When the pointer is moved past the last element (or the array is empty), key() returns null.

This is different from array_key_exists(), which checks whether a specific key is present, and from array_keys(), which returns all keys at once. key() is about one position: wherever the pointer happens to be right now.

Syntax

key(array $array): int|string|null

It takes a single argument — the array to read — and returns the current key as an int or string, or null if the pointer is out of range.

Example 1: Reading the current key

When you create or reset() an array, the pointer starts on the first element, so key() returns that first key.

<?php

$fruits = ["apple", "banana", "cherry"];
echo key($fruits);
?>

Output: 0

The pointer is on the first element, whose key is the index 0, so key() returns 0.

Example 2: Moving the pointer with next() and prev()

key() becomes useful once the pointer moves. next() advances it one step and prev() rewinds it; key() reports where it landed each time.

<?php

$capitals = ["France" => "Paris", "Japan" => "Tokyo", "Egypt" => "Cairo"];

echo "Current key: " . key($capitals) . "\n";
next($capitals);
echo "After next(): " . key($capitals) . "\n";
prev($capitals);
echo "After prev(): " . key($capitals) . "\n";
?>

Output:
Current key: France
After next(): Japan
After prev(): France

Because the keys are strings, key() returns the string key at each pointer position rather than a numeric index.

Walking an array with key() and current()

A common pattern is to iterate manually while you need both the key and the value. The loop stops when key() returns null, which signals the pointer has run off the end of the array.

<?php

$colors = ["red", "green", "blue"];

while (($key = key($colors)) !== null) {
    echo $key . " => " . current($colors) . "\n";
    next($colors);
}
?>

Output:
0 => red
1 => green
2 => blue

Use the strict !== null comparison: a loop like while (key($arr)) would break early on a falsy key such as 0 or an empty string. In most code a foreach loop is clearer, but manual pointer control with key()/next() is handy when you advance through an array conditionally or from inside more than one loop.

When key() returns null

key() returns null in two situations: the array is empty, or the internal pointer has been moved beyond the last element.

<?php

$data = ["a" => 1, "b" => 2];

var_dump(key([]));   // empty array

end($data);          // pointer on last element
next($data);         // pointer pushed past the end
var_dump(key($data));
?>

Output:
NULL
NULL

Both calls return NULL: the first because the array has no elements, the second because next() moved the pointer past "b". Calling reset($data) would move the pointer back to the first element so key() returns "a" again.

Common pitfalls

• key() reads, it never moves. Calling it twice in a row returns the same key. Use next() or prev() to change position.
• Pass by reference. key() works on the array's internal pointer, so it cannot be used directly on the return value of a function — assign it to a variable first.
• null value vs. null key. If the value at the current position is null, key() still returns the real key; only an out-of-range pointer yields a null key.
• Prefer foreach for simple iteration. Reach for key()/next()/prev() only when you need explicit, step-by-step pointer control.

Conclusion

The key() function returns the key of the element under an array's internal pointer, returning null when that pointer is out of range. Paired with current(), next() and prev(), it lets you walk an array one position at a time and read each key as you go — a precise tool for the cases where a plain foreach is not enough.

Practice