key()

Introduction

Every PHP array keeps an internal pointer that marks one of its elements as the "current" one. The key() function returns the key of whatever element that pointer is on. It is part of the same family as current(), next(), prev(), reset(), and end() — the functions that let you walk an array by hand instead of with foreach.

This page explains the syntax, what key() returns (including when it returns null), and how it cooperates with the other pointer functions.

Syntax

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

It takes a single argument — the array to inspect — and returns the key at the current pointer position. The array is passed by value, so key() itself does not move the pointer.

Return value:

• The current key as an int or string.
• null if the array is empty, or if the pointer has been advanced beyond the last element.

Basic example

key() reads the key without changing position; next() moves the pointer forward.

<?php

$fruits = ['a' => 'apple', 'b' => 'banana', 'c' => 'cherry'];

echo key($fruits) . "\n";   // a  (pointer starts on the first element)

next($fruits);              // move the pointer forward
echo key($fruits) . "\n";   // b

Output:

a
b

Numeric keys

When an array has no explicit keys, PHP uses sequential integer keys starting at 0, and key() returns those integers:

<?php

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

echo key($colors) . "\n";   // 0

Output:

0

When key() returns null

key() returns null in two situations: the array is empty, or the pointer has run off the end. Checking for null is the idiomatic way to detect both:

<?php

$empty = [];
var_dump(key($empty));      // NULL — nothing to point at

$colors = ['red', 'green', 'blue'];
end($colors);               // pointer on the last element
next($colors);              // move past the end
var_dump(key($colors));     // NULL

Output:

NULL
NULL

Note: Because a valid key can be the integer 0 (which is falsy), always compare with === null rather than a loose truthiness check when you test whether the pointer is still in range.

Walking an array manually

Combining key(), current(), and next() lets you iterate over an array while keeping access to both the key and the value, stopping cleanly when key() hits null:

<?php

$user = ['name' => 'Sara', 'role' => 'admin', 'active' => true];

reset($user);                       // make sure we start at the beginning
while (key($user) !== null) {
    echo key($user) . " => " . current($user) . "\n";
    next($user);
}

Output:

name => Sara
role => admin
active => 1

(true prints as 1 because PHP casts a boolean to a string when echoed.)

When to use it

In everyday code, foreach already gives you $key => $value and is the right choice for simple iteration. Reach for key() and the manual pointer functions when you need finer control — for example, processing several arrays in lockstep, peeking at the current key without consuming the element, or implementing a custom traversal that foreach can't express.

Conclusion

The key() function returns the key of the element at an array's internal pointer, or null when there is nothing valid to point at. It rarely stands alone: paired with current(), next(), prev(), and reset(), it gives you manual, step-by-step control over array traversal — useful whenever foreach is too coarse for the job.

Practice