key()

Introduzione

Ogni array PHP mantiene un puntatore interno che segna uno dei suoi elementi come "corrente". La funzione key() restituisce la chiave dell'elemento su cui si trova quel puntatore. Fa parte della stessa famiglia di current(), next(), prev(), reset() e end() — le funzioni che permettono di scorrere un array manualmente invece di usare foreach.

Questa pagina spiega la sintassi, cosa restituisce key() (incluso quando restituisce null) e come si coordina con le altre funzioni di puntatore.

Sintassi

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

Accetta un solo argomento — l'array da ispezionare — e restituisce la chiave nella posizione corrente del puntatore. L'array viene passato per valore, quindi key() di per sé non sposta il puntatore.

Valore restituito:

• La chiave corrente come int o string.
• null se l'array è vuoto, oppure se il puntatore è stato avanzato oltre l'ultimo elemento.

Esempio base

key() legge la chiave senza cambiare posizione; next() sposta il puntatore in avanti.

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

Output:

a
b

Chiavi numeriche

Quando un array non ha chiavi esplicite, PHP usa chiavi intere sequenziali a partire da 0, e key() restituisce questi interi:

<?php

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

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

Output:

0

Quando key() restituisce null

key() restituisce null in due situazioni: l'array è vuoto, oppure il puntatore ha superato la fine. Verificare null è il modo idiomatico per rilevare entrambe le condizioni:

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

Output:

NULL
NULL

Nota: Poiché una chiave valida può essere l'intero 0 (che è falsy), usa sempre il confronto con === null anziché un controllo di veridicità generico quando vuoi verificare se il puntatore è ancora nell'intervallo valido.

Scorrere un array manualmente

Combinando key(), current() e next() è possibile iterare su un array mantenendo l'accesso sia alla chiave che al valore, fermandosi correttamente quando key() restituisce 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);
}

Output:

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

(true viene stampato come 1 perché PHP converte un booleano in stringa quando viene usato con echo.)

Quando usarla

Nel codice quotidiano, foreach fornisce già $key => $value ed è la scelta giusta per iterazioni semplici. Ricorri a key() e alle funzioni di puntatore manuale quando hai bisogno di un controllo più fine — ad esempio, per elaborare più array in parallelo, per spiare la chiave corrente senza consumare l'elemento, o per implementare una traversata personalizzata che foreach non può esprimere.

Conclusione

La funzione key() restituisce la chiave dell'elemento in corrispondenza del puntatore interno di un array, o null quando non c'è nulla di valido a cui puntare. Raramente viene usata da sola: abbinata a current(), next(), prev() e reset(), offre un controllo manuale passo dopo passo sulla traversata degli array — utile ogni volta che foreach è troppo grossolano per il compito.

Pratica