PHP Generatoren: yield, yield from und Speicherbedarf

Ein Generator ist eine Funktion, die yield enthält. Ihr Aufruf führt den Rumpf nicht aus; er liefert ein Generator-Objekt, über das foreach iterieren kann. Jedes yield $value gibt der Schleife einen Wert und pausiert die Funktion, bis die Schleife den nächsten anfordert, sodass Werte einzeln erzeugt werden, statt zuerst in einem Array gesammelt zu werden.

<?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";
}

Die Ausgabe wechselt zwischen Generator und Schleife: Jeder Wert wird erst erzeugt, wenn die Schleife ihn anfordert.

Generatoren sparen Speicher

range(1, 1000000) baut ein Array mit einer Million Ganzzahlen auf, bevor die Schleife beginnt. Ein Generator, der dieselben Zahlen liefert, hält nie mehr als eine davon. Führe es aus und vergleiche, wie viel Speicher jede Version braucht:

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

Beide Schleifen geben dieselbe Summe aus, 500000500000, aber die Array-Version meldet extra memory 16.0 MB und der Generator extra memory 0.0 MB. Der Abstand wächst mit den Daten. Genau diese Idee macht Generatoren nützlich für große Dateien, Datenbankergebnisse und API-Seiten: einen Eintrag verarbeiten, wegwerfen, den nächsten nehmen.

Schlüssel und Werte mit yield liefern

yield $key => $value setzt den Schlüssel, den foreach ($gen as $key => $value) bekommt. Ohne Schlüssel nummeriert ein Generator seine Werte ab 0, wie eine Liste. Ein typischer Einsatz ist, eine Datei Zeile für Zeile mit Zeilennummern zu lesen:

<?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";
    }
}

Es liegt immer nur eine Zeile im Speicher, also verarbeitet dieselbe Funktion auch eine Logdatei mit 2 GB. fopen() und fgets() behandeln die hier verwendeten Dateifunktionen.

Unendliche Folgen und lazy Pipelines

Ein Generator kann endlos laufen, weil er nur so weit läuft, wie der Verbraucher anfragt. Stoppe mit break oder pack ihn in einen weiteren Generator, der die ersten paar Werte nimmt. Kleine Generatoren hintereinander ergeben eine Pipeline, in der jeder Schritt lazy ist:

<?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() endet nie von selbst, und trotzdem ist das Programm fertig: take() hört nach der gewünschten Anzahl auf zu fragen, und nichts darüber hinaus wird je berechnet.

yield from: an einen anderen Generator delegieren

yield from reicht jeden Wert eines Arrays, eines Iterators oder eines anderen Generators durch. So teilst du einen Generator in kleinere auf oder läufst rekursiv durch eine verschachtelte Struktur:

<?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 behält die inneren Schlüssel, also liefern beide Arrays die Schlüssel 0 und 1. iterator_to_array() überschreibt dann a und b. Übergib false als zweites Argument, wann immer nur die Werte zählen.

send() und getReturn()

Ein Generator kann auch Werte empfangen. $x = yield; pausiert und wartet; $gen->send($value) setzt den Generator fort, mit $value als Ergebnis dieses yield. Und ein Generator kann mit return einen Endwert liefern, den du mit getReturn() liest, sobald er fertig ist.

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

Die meisten brauchen send() nie; lazy Lesen mit foreach ist der Alltagseinsatz. Es ist der Baustein hinter Coroutine-Bibliotheken.

Über einen Generator lässt sich nur einmal iterieren

Generatoren laufen vorwärts und lassen sich nicht zurückspulen. Sobald ein foreach einen verbraucht hat, wirft eine zweite Schleife über dasselbe Objekt einen Fehler:

<?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";
}

Die Lösung ist, die Generatorfunktion für jeden Durchgang neu aufzurufen, foreach (colors() as $c), oder die Werte einmal mit iterator_to_array(colors(), false) zu sammeln, wenn du sie wirklich zweimal brauchst. Wenn du das oft tust, wäre ein einfaches Array für diese Daten die richtige Wahl gewesen.