key()

Введение

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

На этой странице описаны синтаксис, возвращаемые значения key() (включая случай, когда возвращается null), а также взаимодействие функции с другими функциями работы с указателями.

Синтаксис

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

Функция принимает один аргумент — массив для проверки — и возвращает ключ в текущей позиции указателя. Массив передаётся по значению, поэтому key() сама по себе не перемещает указатель.

Возвращаемое значение:

• Текущий ключ в виде int или string.
• null, если массив пуст или указатель вышел за пределы последнего элемента.

Базовый пример

key() читает ключ, не изменяя позицию; next() перемещает указатель вперёд.

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

Вывод:

a
b

Числовые ключи

Если массив не имеет явных ключей, PHP использует последовательные целочисленные ключи, начиная с 0, и key() возвращает именно эти целые числа:

<?php

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

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

Вывод:

0

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

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

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

Вывод:

NULL
NULL

Примечание: Поскольку допустимым ключом может быть целое число 0 (которое является ложным), при проверке того, находится ли указатель ещё в пределах массива, всегда используйте сравнение === null, а не нестрогую проверку истинности.

Обход массива вручную

Сочетание key(), current() и next() позволяет перебирать массив с доступом одновременно к ключу и значению, чисто останавливаясь, когда key() возвращает 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);
}

Вывод:

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

(true выводится как 1, потому что PHP приводит boolean к строке при использовании echo.)

Когда использовать

В повседневном коде foreach уже предоставляет конструкцию $key => $value и является правильным выбором для простой итерации. Обращайтесь к key() и функциям ручного управления указателем, когда нужен более тонкий контроль — например, при синхронной обработке нескольких массивов, просмотре текущего ключа без потребления элемента или реализации пользовательского обхода, который нельзя выразить через foreach.

Заключение

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

Практика