CKTIS / PHP
Iterator::key — Ler a chave do elemento atual
Lê a chave do elemento atual sem avançar o iterador e vê como o PHP atribui essa chave numa estrutura `foreach`.
Versão: PHP 8.3
Sintaxe
public function key(): mixed
$iterator->key();Iterator::key é um método público de instância sem parâmetros. Chama $iterator->key() para ler a chave na posição atual sem mover o iterador. current() lê o valor nessa mesma posição, next() avança e rewind() volta ao início.
Em foreach ($iterator as $key => $value), o PHP chama rewind() no início e verifica valid() antes de cada iteração. Numa posição válida, lê o valor com current() e a chave com key(). Após uma passagem normal pelo corpo do ciclo, chama next(). Ao percorrer o iterador manualmente, verifica valid() em vez de testares a chave: 0 pode ser uma chave válida.
O tipo de retorno mixed não limita as chaves a int e string: por exemplo, MultipleIterator::key() devolve um array. ArrayIterator::key() tem uma assinatura mais restrita: string|int|null. O manual da interface indica null e E_NOTICE em caso de falha, mas não partas do princípio de que todas as implementações se comportam assim numa posição inválida. Em PHP 8.3, declara public function key(): mixed ou um tipo de retorno compatível mais restrito na tua implementação, para evitares um aviso de descontinuação relacionado com a assinatura.
Não confundas o método com a função global \key($array), que devolve a chave do elemento para o qual aponta o ponteiro interno do array. Passar um objeto a essa função é uma prática assinalada como obsoleta desde o PHP 8.1.
Exemplos
<?php
$iterator = new \ArrayIterator([0 => 'oak', 'tree' => 'pine']);
$iterator->rewind();
if ($iterator->valid()) {
echo $iterator->key(), ', ', $iterator->key(), "\n";
}
$iterator->next();
if ($iterator->valid()) {
echo $iterator->key(), "\n";
}
foreach ($iterator as $key => $value) {
echo $key, ' => ', $value, "\n";
}
Resultado
0, 0 tree 0 => oak tree => pine
O exemplo usa `\ArrayIterator` da SPL. As duas leituras devolvem `0`; `next()` move o iterador para `tree`. O ciclo `foreach` recomeça no início e apresenta os dois pares.
Lições relacionadas
- PHP · Lição 61 · Avançado · Versão: 2
- PHP · Lição 63 · Avançado · Versão: 2