key()

Introduzione

Ogni array PHP mantiene un puntatore interno che segna un elemento come quello "corrente". La funzione key() legge la chiave (non il valore) dell'elemento su cui si trova quel puntatore. È la controparte di current(), che restituisce il valore nella stessa posizione, e viene utilizzata più spesso insieme a next() e prev() per scorrere un array manualmente. Questo capitolo spiega cosa restituisce key(), come si sposta il puntatore interno, i casi limite che restituiscono null e i pattern pratici in cui key() è genuinamente utile.

Capire la funzione key()

key() restituisce la chiave dell'elemento su cui punta attualmente il puntatore interno dell'array. Non fa avanzare il puntatore — si limita a leggere la posizione corrente. Quando il puntatore viene spostato oltre l'ultimo elemento (o l'array è vuoto), key() restituisce null.

Questo è diverso da array_key_exists(), che controlla se una chiave specifica è presente, e da array_keys(), che restituisce tutte le chiavi in una volta. key() riguarda una sola posizione: quella in cui si trova il puntatore in questo momento.

Sintassi

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

Accetta un singolo argomento — l'array da leggere — e restituisce la chiave corrente come int o string, oppure null se il puntatore è fuori intervallo.

Esempio 1: Leggere la chiave corrente

Quando si crea o si esegue reset() su un array, il puntatore parte dal primo elemento, quindi key() restituisce quella prima chiave.

<?php

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

Output: 0

Il puntatore è sul primo elemento, la cui chiave è l'indice 0, quindi key() restituisce 0.

Esempio 2: Spostare il puntatore con next() e prev()

key() diventa utile una volta che il puntatore si muove. next() lo fa avanzare di un passo e prev() lo riporta indietro; key() riporta dove si è fermato ogni volta.

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

Poiché le chiavi sono stringhe, key() restituisce la chiave stringa a ogni posizione del puntatore anziché un indice numerico.

Scorrere un array con key() e current()

Un pattern comune è iterare manualmente quando si ha bisogno sia della chiave che del valore. Il ciclo si ferma quando key() restituisce null, il che segnala che il puntatore è uscito dall'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

Usa il confronto stretto !== null: un ciclo come while (key($arr)) si interromperebbe anticipatamente su una chiave falsa come 0 o una stringa vuota. Nella maggior parte del codice un ciclo foreach è più chiaro, ma il controllo manuale del puntatore con key()/next() è utile quando si avanza nell'array in modo condizionale o dall'interno di più cicli.

Quando key() restituisce null

key() restituisce null in due situazioni: l'array è vuoto, oppure il puntatore interno è stato spostato oltre l'ultimo 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

Entrambe le chiamate restituiscono NULL: la prima perché l'array non ha elementi, la seconda perché next() ha spostato il puntatore oltre "b". Chiamare reset($data) riporterebbe il puntatore al primo elemento, così key() restituirebbe di nuovo "a".

Errori comuni

• key() legge, non sposta mai. Chiamarla due volte di fila restituisce la stessa chiave. Usa next() o prev() per cambiare posizione.
• Passaggio per riferimento. key() opera sul puntatore interno dell'array, quindi non può essere usata direttamente sul valore restituito da una funzione — assegnalo prima a una variabile.
• Valore null vs. chiave null. Se il valore nella posizione corrente è null, key() restituisce comunque la chiave reale; solo un puntatore fuori intervallo produce una chiave null.
• Preferire foreach per la semplice iterazione. Ricorri a key()/next()/prev() solo quando hai bisogno di un controllo esplicito del puntatore passo dopo passo.

Conclusione

La funzione key() restituisce la chiave dell'elemento sotto il puntatore interno di un array, restituendo null quando quel puntatore è fuori intervallo. Abbinata a current(), next() e prev(), ti permette di scorrere un array una posizione alla volta e leggere ogni chiave man mano che procedi — uno strumento preciso per i casi in cui un semplice foreach non è sufficiente.

Pratica