key()

Introducción

Todo array de PHP mantiene un puntero interno que marca un elemento como el "actual". La función key() lee la clave (no el valor) del elemento en el que se encuentra ese puntero. Es la compañera de current(), que devuelve el valor en la misma posición, y se utiliza con mayor frecuencia junto con next() y prev() para recorrer un array manualmente. Este capítulo explica qué devuelve key(), cómo se mueve el puntero interno, los casos límite que devuelven null y los patrones prácticos en los que key() resulta genuinamente útil.

Comprendiendo la función key()

key() devuelve la clave del elemento al que apunta actualmente el puntero interno del array. No avanza el puntero — solo lee la posición actual. Cuando el puntero se mueve más allá del último elemento (o el array está vacío), key() devuelve null.

Esto es diferente de array_key_exists(), que comprueba si una clave específica está presente, y de array_keys(), que devuelve todas las claves a la vez. key() se refiere a una sola posición: dondequiera que se encuentre el puntero en ese momento.

Sintaxis

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

Toma un único argumento — el array a leer — y devuelve la clave actual como int o string, o null si el puntero está fuera de rango.

Ejemplo 1: Leer la clave actual

Cuando creas o aplicas reset() a un array, el puntero comienza en el primer elemento, por lo que key() devuelve esa primera clave.

<?php

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

Output: 0

El puntero está en el primer elemento, cuya clave es el índice 0, por lo que key() devuelve 0.

Ejemplo 2: Mover el puntero con next() y prev()

key() se vuelve útil una vez que el puntero se mueve. next() lo avanza un paso y prev() lo retrocede; key() informa dónde aterrizó en cada ocasión.

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

Como las claves son cadenas de texto, key() devuelve la clave de tipo string en cada posición del puntero, en lugar de un índice numérico.

Recorrer un array con key() y current()

Un patrón común es iterar manualmente cuando se necesita tanto la clave como el valor. El bucle se detiene cuando key() devuelve null, lo que indica que el puntero ha llegado al final del 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

Utiliza la comparación estricta !== null: un bucle como while (key($arr)) terminaría antes de tiempo con una clave de valor falsy como 0 o una cadena vacía. En la mayoría del código un bucle foreach es más claro, pero el control manual del puntero con key()/next() resulta útil cuando avanzas por un array de forma condicional o desde dentro de más de un bucle.

Cuándo key() devuelve null

key() devuelve null en dos situaciones: el array está vacío, o el puntero interno se ha movido más allá del último elemento.

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

Ambas llamadas devuelven NULL: la primera porque el array no tiene elementos, la segunda porque next() movió el puntero más allá de "b". Llamar a reset($data) devolvería el puntero al primer elemento, de modo que key() retornaría "a" nuevamente.

Errores comunes

• key() solo lee, nunca mueve. Llamarlo dos veces seguidas devuelve la misma clave. Usa next() o prev() para cambiar de posición.
• Paso por referencia. key() trabaja sobre el puntero interno del array, por lo que no puede usarse directamente con el valor de retorno de una función — asígnalo primero a una variable.
• Valor null vs. clave null. Si el valor en la posición actual es null, key() aún devuelve la clave real; solo un puntero fuera de rango produce una clave null.
• Prefiere foreach para la iteración simple. Recurre a key()/next()/prev() solo cuando necesites un control de puntero explícito, paso a paso.

Conclusión

La función key() devuelve la clave del elemento bajo el puntero interno de un array, retornando null cuando ese puntero está fuera de rango. Combinada con current(), next() y prev(), te permite recorrer un array de una posición en una y leer cada clave a medida que avanzas — una herramienta precisa para los casos en que un simple foreach no es suficiente.

Práctica