key()

Introdução

Todo array PHP mantém um ponteiro interno que marca um de seus elementos como o "atual". A função key() retorna a chave do elemento em que esse ponteiro se encontra. Ela faz parte da mesma família de current(), next(), prev(), reset() e end() — as funções que permitem percorrer um array manualmente em vez de usar foreach.

Esta página explica a sintaxe, o que key() retorna (incluindo quando retorna null) e como ela funciona em conjunto com as demais funções de ponteiro.

Sintaxe

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

Recebe um único argumento — o array a ser inspecionado — e retorna a chave na posição atual do ponteiro. O array é passado por valor, portanto key() em si não move o ponteiro.

Valor de retorno:

• A chave atual como int ou string.
• null se o array estiver vazio ou se o ponteiro tiver avançado além do último elemento.

Exemplo básico

key() lê a chave sem alterar a posição; next() move o ponteiro para frente.

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

Saída:

a
b

Chaves numéricas

Quando um array não possui chaves explícitas, o PHP utiliza chaves inteiras sequenciais a partir de 0, e key() retorna esses inteiros:

<?php

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

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

Saída:

0

Quando key() retorna null

key() retorna null em duas situações: o array está vazio ou o ponteiro ultrapassou o final. Verificar null é a forma idiomática de detectar ambos os casos:

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

Saída:

NULL
NULL

Nota: Como uma chave válida pode ser o inteiro 0 (que é falsy), sempre compare com === null em vez de uma verificação de veracidade solta ao testar se o ponteiro ainda está dentro do intervalo.

Percorrendo um array manualmente

Combinar key(), current() e next() permite iterar sobre um array mantendo acesso tanto à chave quanto ao valor, parando de forma limpa quando key() retorna 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);
}

Saída:

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

(true é impresso como 1 porque o PHP converte um boolean para string ao fazer echo.)

Quando utilizá-la

No código do dia a dia, o foreach já fornece $key => $value e é a escolha certa para iterações simples. Recorra a key() e às funções manuais de ponteiro quando precisar de controle mais refinado — por exemplo, processar vários arrays em sincronia, verificar a chave atual sem consumir o elemento ou implementar uma travessia personalizada que o foreach não consegue expressar.

Conclusão

A função key() retorna a chave do elemento na posição do ponteiro interno de um array, ou null quando não há nada válido a apontar. Raramente é usada sozinha: combinada com current(), next(), prev() e reset(), oferece controle manual e passo a passo sobre a travessia de arrays — útil sempre que o foreach for refinado demais para a tarefa.

Prática