Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

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

Fontes