key()

Введение

Каждый массив PHP хранит внутренний указатель, который отмечает один элемент как «текущий». Функция key() возвращает ключ (не значение) того элемента, на который указывает этот указатель. Она является парной к current(), возвращающей значение в той же позиции, и чаще всего используется вместе с next() и prev() для ручного обхода массива. В этой главе объясняется, что возвращает key(), как перемещается внутренний указатель, какие граничные случаи дают null, и в каких практических ситуациях key() действительно полезна.

Понимание функции key()

key() возвращает ключ элемента, на который в данный момент указывает внутренний указатель массива. Она не перемещает указатель — только считывает текущую позицию. Когда указатель выходит за пределы последнего элемента (или массив пуст), key() возвращает null.

Это отличает её от array_key_exists(), проверяющей наличие конкретного ключа, и от array_keys(), возвращающей все ключи сразу. key() работает с одной позицией: там, где в данный момент находится указатель.

Синтаксис

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

Функция принимает один аргумент — массив для чтения — и возвращает текущий ключ как int или string, либо null, если указатель вышел за допустимый диапазон.

Пример 1: чтение текущего ключа

При создании массива или после вызова reset() указатель находится на первом элементе, поэтому key() возвращает первый ключ.

<?php

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

Output: 0

Указатель стоит на первом элементе, ключ которого — индекс 0, поэтому key() возвращает 0.

Пример 2: перемещение указателя с помощью next() и prev()

key() становится полезной, когда указатель перемещается. next() сдвигает его на один шаг вперёд, prev() — на один шаг назад; key() сообщает, на какой позиции он оказался.

<?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

Поскольку ключи являются строками, key() возвращает строковый ключ в каждой позиции указателя, а не числовой индекс.

Обход массива с помощью key() и current()

Распространённый шаблон — ручная итерация, когда нужны одновременно и ключ, и значение. Цикл останавливается, когда key() возвращает null: это сигнал о том, что указатель вышел за конец массива.

<?php

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

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

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

Используйте строгое сравнение !== null: цикл вида while (key($arr)) прервётся раньше времени на ложном ключе — например, 0 или пустой строке. В большинстве случаев цикл foreach нагляднее, однако ручное управление указателем через key()/next() удобно, когда вы продвигаетесь по массиву условно или изнутри нескольких циклов.

Когда key() возвращает null

key() возвращает null в двух случаях: массив пуст или внутренний указатель перемещён за последний элемент.

<?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

Оба вызова возвращают NULL: первый — потому что в массиве нет элементов, второй — потому что next() переместил указатель за "b". Вызов reset($data) вернёт указатель на первый элемент, и key() снова вернёт "a".

Распространённые ловушки

• key() только читает, никогда не перемещает. Два последовательных вызова возвращают один и тот же ключ. Для изменения позиции используйте next() или prev().
• Передача по ссылке. key() работает с внутренним указателем массива, поэтому её нельзя применять непосредственно к возвращаемому значению функции — сначала присвойте его переменной.
• null как значение против null как ключа. Если значение текущего элемента равно null, key() всё равно возвращает реальный ключ; null в качестве ключа возникает только тогда, когда указатель вышел за допустимый диапазон.
• Предпочитайте foreach для простой итерации. Обращайтесь к key()/next()/prev() только тогда, когда нужен явный пошаговый контроль указателя.

Заключение

Функция key() возвращает ключ элемента, на который указывает внутренний указатель массива, и возвращает null, когда этот указатель вышел за допустимый диапазон. В паре с current(), next() и prev() она позволяет обходить массив по одной позиции за раз и читать каждый ключ по мере продвижения — точный инструмент для случаев, когда простого foreach недостаточно.

Практика