key()

Introduction

Chaque tableau PHP possède un pointeur interne qui désigne un élément comme l'élément « courant ». La fonction key() lit la clé (et non la valeur) de l'élément sur lequel ce pointeur est positionné. Elle est le pendant de current(), qui retourne la valeur à la même position, et elle est le plus souvent utilisée conjointement avec next() et prev() pour parcourir un tableau manuellement. Ce chapitre explique ce que retourne key(), comment le pointeur interne se déplace, les cas particuliers qui renvoient null, ainsi que les situations pratiques où key() est véritablement utile.

Comprendre la fonction key()

key() retourne la clé de l'élément sur lequel pointe actuellement le pointeur interne du tableau. Elle n'avance pas le pointeur — elle se contente de lire la position courante. Lorsque le pointeur dépasse le dernier élément (ou que le tableau est vide), key() retourne null.

Cela diffère de array_key_exists(), qui vérifie si une clé spécifique est présente, et de array_keys(), qui retourne toutes les clés d'un coup. key() concerne une seule position : là où se trouve le pointeur à l'instant présent.

Syntaxe

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

Elle prend un seul argument — le tableau à lire — et retourne la clé courante sous forme d'int ou de string, ou null si le pointeur est hors limites.

Exemple 1 : Lire la clé courante

Lorsque vous créez ou réinitialisez (reset()) un tableau, le pointeur se place sur le premier élément, donc key() retourne cette première clé.

<?php

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

Output: 0

Le pointeur est sur le premier élément, dont la clé est l'indice 0, donc key() retourne 0.

Exemple 2 : Déplacer le pointeur avec next() et prev()

key() devient utile dès que le pointeur se déplace. next() l'avance d'un pas et prev() le recule ; key() indique à chaque fois où il s'est arrêté.

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

Les clés étant des chaînes de caractères, key() retourne la clé string à chaque position du pointeur plutôt qu'un indice numérique.

Parcourir un tableau avec key() et current()

Un schéma courant consiste à itérer manuellement lorsque vous avez besoin à la fois de la clé et de la valeur. La boucle s'arrête quand key() retourne null, ce qui signale que le pointeur a dépassé la fin du tableau.

<?php

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

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

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

Utilisez la comparaison stricte !== null : une boucle comme while (key($arr)) s'arrêterait prématurément sur une clé à valeur fausse telle que 0 ou une chaîne vide. Dans la plupart des cas, une boucle foreach est plus lisible, mais le contrôle manuel du pointeur avec key()/next() est pratique lorsque vous avancez dans un tableau de manière conditionnelle ou depuis plusieurs boucles imbriquées.

Quand key() retourne null

key() retourne null dans deux situations : le tableau est vide, ou le pointeur interne a été déplacé au-delà du dernier élément.

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

Les deux appels retournent NULL : le premier parce que le tableau ne contient aucun élément, le second parce que next() a déplacé le pointeur au-delà de "b". Appeler reset($data) ramènerait le pointeur sur le premier élément, de sorte que key() retournerait à nouveau "a".

Pièges courants

• key() lit, elle ne déplace jamais le pointeur. L'appeler deux fois de suite retourne la même clé. Utilisez next() ou prev() pour changer de position.
• Passage par référence. key() travaille sur le pointeur interne du tableau ; elle ne peut donc pas être utilisée directement sur la valeur de retour d'une fonction — assignez d'abord cette valeur à une variable.
• Valeur null vs clé null. Si la valeur à la position courante est null, key() retourne quand même la vraie clé ; seul un pointeur hors limites produit une clé null.
• Préférez foreach pour les itérations simples. N'ayez recours à key()/next()/prev() que lorsque vous avez besoin d'un contrôle explicite, pas à pas, du pointeur.

Conclusion

La fonction key() retourne la clé de l'élément pointé par le pointeur interne d'un tableau, et renvoie null lorsque ce pointeur est hors limites. Associée à current(), next() et prev(), elle vous permet de parcourir un tableau une position à la fois et de lire chaque clé au fil du chemin — un outil précis pour les cas où un simple foreach ne suffit pas.

Pratique