key()

Introdução

Todo array PHP mantém um ponteiro interno que marca um elemento como o "atual". A função key() lê a chave (não o valor) do elemento em que esse ponteiro está posicionado. Ela é a parceira de current(), que retorna o valor na mesma posição, e é usada com mais frequência junto com next() e prev() para percorrer um array manualmente. Este capítulo explica o que key() retorna, como o ponteiro interno se move, os casos extremos que retornam null e os padrões práticos em que key() é genuinamente útil.

Entendendo a função key()

key() retorna a chave do elemento para o qual o ponteiro interno do array aponta atualmente. Ela não avança o ponteiro — apenas lê a posição atual. Quando o ponteiro é movido além do último elemento (ou o array está vazio), key() retorna null.

Isso é diferente de array_key_exists(), que verifica se uma chave específica está presente, e de array_keys(), que retorna todas as chaves de uma vez. key() trata de uma posição: onde quer que o ponteiro esteja no momento.

Sintaxe

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

Ela recebe um único argumento — o array a ser lido — e retorna a chave atual como int ou string, ou null se o ponteiro estiver fora do intervalo.

Exemplo 1: Lendo a chave atual

Quando você cria ou aplica reset() em um array, o ponteiro começa no primeiro elemento, então key() retorna essa primeira chave.

<?php

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

Output: 0

O ponteiro está no primeiro elemento, cuja chave é o índice 0, então key() retorna 0.

Exemplo 2: Movendo o ponteiro com next() e prev()

key() torna-se útil quando o ponteiro se move. next() avança um passo e prev() o retrocede; key() informa onde ele parou a cada vez.

<?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 as chaves são strings, key() retorna a chave string em cada posição do ponteiro, em vez de um índice numérico.

Percorrendo um array com key() e current()

Um padrão comum é iterar manualmente quando você precisa tanto da chave quanto do valor. O loop para quando key() retorna null, o que sinaliza que o ponteiro ultrapassou o fim do 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

Use a comparação estrita !== null: um loop como while (key($arr)) quebraria cedo em uma chave falsy como 0 ou uma string vazia. Na maioria dos códigos, um loop foreach é mais claro, mas o controle manual do ponteiro com key()/next() é útil quando você avança por um array condicionalmente ou de dentro de mais de um loop.

Quando key() retorna null

key() retorna null em duas situações: o array está vazio ou o ponteiro interno foi movido além do ú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 as chamadas retornam NULL: a primeira porque o array não tem elementos, a segunda porque next() moveu o ponteiro além de "b". Chamar reset($data) moveria o ponteiro de volta ao primeiro elemento, de modo que key() retornaria "a" novamente.

Armadilhas comuns

• key() lê, nunca move. Chamá-la duas vezes seguidas retorna a mesma chave. Use next() ou prev() para mudar de posição.
• Passagem por referência. key() opera no ponteiro interno do array, portanto não pode ser usada diretamente no valor de retorno de uma função — atribua-o a uma variável primeiro.
• Valor null vs. chave null. Se o valor na posição atual for null, key() ainda retorna a chave real; apenas um ponteiro fora do intervalo produz uma chave null.
• Prefira foreach para iteração simples. Recorra a key()/next()/prev() somente quando precisar de controle explícito e passo a passo do ponteiro.

Conclusão

A função key() retorna a chave do elemento sob o ponteiro interno de um array, retornando null quando esse ponteiro está fora do intervalo. Combinada com current(), next() e prev(), ela permite percorrer um array uma posição por vez e ler cada chave ao longo do caminho — uma ferramenta precisa para os casos em que um simples foreach não é suficiente.

Prática