key()

Introduction

Chaque tableau PHP maintient un pointeur interne qui désigne l'un de ses éléments comme élément « courant ». La fonction key() retourne la clé de l'élément sur lequel ce pointeur est positionné. Elle fait partie de la même famille que current(), next(), prev(), reset() et end() — les fonctions qui permettent de parcourir un tableau manuellement plutôt qu'avec foreach.

Cette page explique la syntaxe, ce que key() retourne (notamment quand elle retourne null) et comment elle coopère avec les autres fonctions de pointeur.

Syntaxe

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

Elle prend un seul argument — le tableau à inspecter — et retourne la clé à la position actuelle du pointeur. Le tableau est passé par valeur, donc key() elle-même ne déplace pas le pointeur.

Valeur de retour :

• La clé courante sous forme d'int ou de string.
• null si le tableau est vide ou si le pointeur a été avancé au-delà du dernier élément.

Exemple de base

key() lit la clé sans changer la position ; next() fait avancer le pointeur.

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

Résultat :

a
b

Clés numériques

Lorsqu'un tableau ne possède pas de clés explicites, PHP utilise des clés entières séquentielles commençant à 0, et key() retourne ces entiers :

<?php

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

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

Résultat :

0

Quand key() retourne null

key() retourne null dans deux situations : le tableau est vide, ou le pointeur a dépassé la fin. Vérifier null est la manière idiomatique de détecter les deux cas :

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

Résultat :

NULL
NULL

Remarque : Comme une clé valide peut être l'entier 0 (qui est faux en contexte booléen), comparez toujours avec === null plutôt qu'un test de vérité approximatif lorsque vous vérifiez si le pointeur est encore dans la plage valide.

Parcourir un tableau manuellement

Combiner key(), current() et next() permet d'itérer sur un tableau tout en conservant l'accès à la clé et à la valeur, en s'arrêtant proprement lorsque key() renvoie 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);
}

Résultat :

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

(true s'affiche sous la forme 1 car PHP convertit un booléen en chaîne lors de l'affichage.)

Quand l'utiliser

Dans le code courant, foreach vous fournit déjà $key => $value et constitue le bon choix pour une itération simple. Recourez à key() et aux fonctions de pointeur manuel lorsque vous avez besoin d'un contrôle plus fin — par exemple, traiter plusieurs tableaux en parallèle, inspecter la clé courante sans consommer l'élément, ou implémenter un parcours personnalisé que foreach ne peut pas exprimer.

Conclusion

La fonction key() retourne la clé de l'élément situé au niveau du pointeur interne d'un tableau, ou null lorsqu'il n'y a rien de valide à pointer. Elle est rarement utilisée seule : associée à current(), next(), prev() et reset(), elle vous offre un contrôle manuel, pas à pas, sur le parcours des tableaux — utile dès que foreach est trop grossier pour la tâche.

Pratique