key()

Introducción

Cada array de PHP mantiene un puntero interno que marca uno de sus elementos como el "actual". La función key() devuelve la clave del elemento en el que se encuentra ese puntero. Forma parte de la misma familia que current(), next(), prev(), reset() y end() — las funciones que permiten recorrer un array manualmente en lugar de usar foreach.

Esta página explica la sintaxis, lo que devuelve key() (incluyendo cuándo devuelve null) y cómo coopera con las demás funciones de puntero.

Sintaxis

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

Acepta un único argumento — el array a inspeccionar — y devuelve la clave en la posición actual del puntero. El array se pasa por valor, por lo que key() en sí mismo no mueve el puntero.

Valor de retorno:

• La clave actual como int o string.
• null si el array está vacío, o si el puntero ha avanzado más allá del último elemento.

Ejemplo básico

key() lee la clave sin cambiar la posición; next() mueve el puntero hacia adelante.

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

Salida:

a
b

Claves numéricas

Cuando un array no tiene claves explícitas, PHP utiliza claves enteras secuenciales comenzando en 0, y key() devuelve esos enteros:

<?php

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

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

Salida:

0

Cuándo key() devuelve null

key() devuelve null en dos situaciones: el array está vacío, o el puntero ha llegado al final. Comprobar null es la forma idiomática de detectar ambos casos:

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

Salida:

NULL
NULL

Nota: Dado que una clave válida puede ser el entero 0 (que es falsy), compara siempre con === null en lugar de una comprobación de veracidad flexible cuando verificas si el puntero sigue dentro del rango.

Recorrer un array manualmente

Combinar key(), current() y next() permite iterar sobre un array manteniendo acceso tanto a la clave como al valor, y detenerse limpiamente cuando key() devuelve 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);
}

Salida:

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

(true se imprime como 1 porque PHP convierte un boolean a string al usar echo.)

Cuándo utilizarla

En el código cotidiano, foreach ya proporciona $key => $value y es la opción correcta para una iteración sencilla. Recurre a key() y las funciones de puntero manual cuando necesites un control más preciso — por ejemplo, procesar varios arrays en paralelo, inspeccionar la clave actual sin consumir el elemento, o implementar un recorrido personalizado que foreach no pueda expresar.

Conclusión

La función key() devuelve la clave del elemento en el puntero interno de un array, o null cuando no hay nada válido a lo que apuntar. Raramente actúa sola: combinada con current(), next(), prev() y reset(), ofrece un control manual paso a paso sobre el recorrido del array — útil siempre que foreach resulte demasiado general para la tarea.

Práctica