Generators no PHP: yield, yield from e uso de memória

Um generator é uma função que contém yield. Chamá-la não executa o corpo; ela retorna um objeto Generator que o foreach consegue percorrer. Cada yield $value entrega um valor ao loop e pausa a função até o loop pedir o próximo, então os valores são produzidos um de cada vez em vez de serem reunidos num array primeiro.

<?php
function countTo(int $n): Generator
{
    for ($i = 1; $i <= $n; $i++) {
        echo "(making $i) ";
        yield $i;
    }
}

foreach (countTo(3) as $number) {
    echo "got $number\n";
}

A saída alterna entre o generator e o loop: cada valor só é produzido quando o loop o pede.

Generators economizam memória

range(1, 1000000) monta um array de um milhão de inteiros antes de o loop começar. Um generator que entrega os mesmos números nunca guarda mais de um deles. Rode e compare a memória de que cada versão precisa:

<?php
function numbers(int $max): Generator
{
    for ($i = 1; $i <= $max; $i++) {
        yield $i;
    }
}

$start = memory_get_usage();
$sum = 0;
foreach (range(1, 1_000_000) as $n) {
    $sum += $n;
}
$arrayPeak = memory_get_peak_usage() - $start;

memory_reset_peak_usage();
$start = memory_get_usage();
$sum2 = 0;
foreach (numbers(1_000_000) as $n) {
    $sum2 += $n;
}
$genPeak = memory_get_peak_usage() - $start;

printf("array:     sum %d, extra memory %.1f MB\n", $sum, $arrayPeak / 1048576);
printf("generator: sum %d, extra memory %.1f MB\n", $sum2, $genPeak / 1048576);

Os dois loops imprimem a mesma soma, 500000500000, mas a versão com array informa extra memory 16.0 MB e o generator extra memory 0.0 MB. A diferença cresce com os dados. A mesma ideia torna os generators úteis para arquivos grandes, resultados de banco de dados e páginas de APIs: processe um item, descarte-o, pegue o próximo.

yield com chaves e valores

yield $key => $value define a chave que foreach ($gen as $key => $value) recebe. Sem chave, um generator numera os valores a partir de 0, como uma lista. Um uso comum é ler um arquivo linha por linha com os números das linhas:

<?php
file_put_contents('log.txt', "boot ok\nERROR disk full\nuser login\nERROR timeout\n");

function readLines(string $path): Generator
{
    $handle = fopen($path, 'r');
    $lineNo = 0;
    while (($line = fgets($handle)) !== false) {
        $lineNo++;
        yield $lineNo => rtrim($line, "\n");
    }
    fclose($handle);
}

foreach (readLines('log.txt') as $no => $line) {
    if (str_starts_with($line, 'ERROR')) {
        echo "line $no: $line\n";
    }
}

Só uma linha fica na memória por vez, então a mesma função lida com um arquivo de log de 2 GB. fopen() e fgets() explicam as funções de arquivo usadas aqui.

Sequências infinitas e pipelines preguiçosos

Um generator pode rodar para sempre, porque só avança até onde o consumidor pede. Pare com break, ou envolva-o em outro generator que pega os primeiros valores. Encadear pequenos generators dá um pipeline em que cada etapa é preguiçosa:

<?php
function fibonacci(): Generator
{
    [$a, $b] = [0, 1];
    while (true) {
        yield $a;
        [$a, $b] = [$b, $a + $b];
    }
}

function take(iterable $items, int $n): Generator
{
    if ($n <= 0) {
        return;
    }
    foreach ($items as $item) {
        yield $item;
        if (--$n === 0) {
            return;
        }
    }
}

function filter(iterable $items, callable $keep): Generator
{
    foreach ($items as $item) {
        if ($keep($item)) {
            yield $item;
        }
    }
}

echo implode(' ', iterator_to_array(take(fibonacci(), 10), false)), "\n";

$evenFibs = take(filter(fibonacci(), fn($x) => $x % 2 === 0), 6);
echo implode(' ', iterator_to_array($evenFibs, false)), "\n";

fibonacci() nunca termina sozinho, mas o programa termina: take() para de pedir depois da quantidade pedida, e nada além disso é calculado.

yield from: delegar a outro generator

yield from repassa cada valor de um array, de um iterator ou de outro generator. É como você divide um generator em menores, ou percorre uma estrutura aninhada de forma recursiva:

<?php
function flatten(array $items): Generator
{
    foreach ($items as $item) {
        if (is_array($item)) {
            yield from flatten($item);   // recurse
        } else {
            yield $item;
        }
    }
}

$nested = [1, [2, 3, [4, 5]], 6, [[7]]];
foreach (flatten($nested) as $v) {
    echo $v, ' ';
}
echo "\n";

// Careful: keys from yield from can repeat
function letters(): Generator
{
    yield from ['a', 'b'];
    yield from ['c', 'd'];
}
print_r(iterator_to_array(letters()));         // keys 0,1,0,1: values overwritten
print_r(iterator_to_array(letters(), false));  // a plain list

yield from mantém as chaves internas, então os dois arrays entregam as chaves 0 e 1. O iterator_to_array() então sobrescreve a e b. Passe false como segundo argumento sempre que só os valores importarem.

send() e getReturn()

Um generator também pode receber valores. $x = yield; pausa e espera; $gen->send($value) retoma o generator com $value como resultado daquele yield. E um generator pode dar return num valor final, que você lê com getReturn() depois que ele terminou.

<?php
function runningAverage(): Generator
{
    $total = 0;
    $count = 0;
    $average = null;
    while (true) {
        $value = yield $average;   // send() puts a value here
        if ($value === null) {
            return $count;         // final result
        }
        $total += $value;
        $count++;
        $average = $total / $count;
    }
}

$avg = runningAverage();
$avg->current();                   // run to the first yield

foreach ([10, 20, 60] as $n) {
    echo "after $n: ", $avg->send($n), "\n";
}

$avg->send(null);                  // ends the loop
echo "values seen: ", $avg->getReturn(), "\n";

A maior parte do código nunca precisa do send(); ler de forma preguiçosa com foreach é o uso do dia a dia. Ele é a peça básica por trás das bibliotecas de corrotinas.

Um generator só pode ser percorrido uma vez

Generators andam para a frente e não podem ser rebobinados. Depois que um foreach consumiu um, um segundo loop sobre o mesmo objeto lança uma exceção:

<?php
// This throws an Exception on purpose: the generator is already finished
function colors(): Generator
{
    yield 'red';
    yield 'green';
}

$gen = colors();
foreach ($gen as $c) {
    echo $c, "\n";
}
foreach ($gen as $c) {   // second pass
    echo $c, "\n";
}

A correção é chamar a função do generator de novo a cada passada, foreach (colors() as $c), ou reunir os valores uma vez com iterator_to_array(colors(), false) quando você realmente precisar deles duas vezes. Se você se pegar fazendo isso com frequência, um array simples era a escolha certa para aqueles dados.