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

CKTIS / PHP

IteratorAggregate::getIterator — delegar a iteração com `foreach`

Implemente `getIterator()` para definir as chaves e os valores que `foreach` lê de um objeto. O método fornece um objeto `Traversable`, não um array.

Versão: PHP 8.3

Sintaxe

public function getIterator(): \Traversable

Em PHP 8.3, IteratorAggregate::getIterator é um método público de instância sem parâmetros. Quando foreach começa a percorrer um objeto que implementa IteratorAggregate, chama este método e obtém as chaves e os valores do objeto devolvido. Ao contrário de uma classe que implementa Iterator, a coleção não tem de gerir por si própria a posição atual.

Em PHP 8.3, o tipo de retorno \Traversable da interface é provisório. Uma implementação pode declarar : \Traversable, como no exemplo, ou um tipo de retorno compatível mais específico (covariância), como : \Generator. O método pode devolver, por exemplo, um \ArrayIterator ou usar yield para fornecer elementos através de um \Generator. Um array não é um objeto Traversable, embora foreach possa percorrer arrays e o tipo iterable os aceite. Devolver um array com o tipo declarado \Traversable provoca um TypeError.

Não é necessária nenhuma extensão opcional: IteratorAggregate, Traversable e os geradores estão integrados no PHP, e ArrayIterator faz parte da extensão obrigatória SPL.

Se a coleção tiver de permitir percursos repetidos ou aninhados, crie um novo iterador a cada chamada. Devolver o mesmo gerador pode impedir um percurso posterior: um gerador não pode recuar até ao início depois de ultrapassar o primeiro yield.

Exemplos

<?php

final class ColorPalette implements \IteratorAggregate
{
    public function getIterator(): \Traversable
    {
        yield 'primary' => 'blue';
        yield 'accent' => 'orange';
    }
}

$palette = new ColorPalette();

for ($pass = 1; $pass <= 2; $pass++) {
    echo "Pass {$pass}:\n";
    foreach ($palette as $role => $color) {
        echo "{$role} = {$color}\n";
    }
}

Resultado

Pass 1:
primary = blue
accent = orange
Pass 2:
primary = blue
accent = orange

Os dois percursos usam a mesma paleta. Cada `foreach` recebe, contudo, um novo gerador, pelo que imprime os mesmos dois pares chave-valor pela mesma ordem.

Lições relacionadas

  • PHP · Lição 62 · Avançado · Versão: 2

Fontes