PHP Generators

Also Known As

TL;DR

Explanation

A generator function uses yield to return values one at a time, pausing execution between yields. The caller receives a Generator object implementing Iterator. Generators consume O(1) memory regardless of the sequence length — ideal for large datasets, file streaming, and infinite sequences. yield from delegates to another generator or iterable. send() passes values back into a paused generator. PHP 5.5+ supports generators; PHP 7.0 added return values from generators.

Common Misconception

Why It Matters

Common Mistakes

• Calling a generator function and expecting an array — it returns a Generator object; use foreach or iterator_to_array().
• Using iterator_to_array() on a large generator — defeats the memory benefit by materialising the full sequence.
• Not using yield from when composing generators — manually looping and yielding is verbose and slower.

Avoid When

• Do not use generators when you need random access to elements — generators are forward-only.
• Avoid calling iterator_to_array() on a generator for large datasets — it loads the full sequence into memory.

When To Use

• Use generators for processing large files, database result sets, or API pagination where loading everything at once would exhaust memory.
• Use generators when you need a lazy sequence — producing values only when requested.

Code Examples

// Loads entire CSV into memory — crashes on large files
function readCsvRows(string $file): array {
    $rows = [];
    $handle = fopen($file, 'r');
    while (($row = fgetcsv($handle)) !== false) {
        $rows[] = $row; // 1M rows = hundreds of MB RAM
    }
    return $rows;
}

// Generator: reads CSV line by line — O(1) memory
function readCsvRows(string $file): \Generator {
    $handle = fopen($file, 'r');
    while (($row = fgetcsv($handle)) !== false) {
        yield $row;
    }
    fclose($handle);
}

foreach (readCsvRows('million_rows.csv') as $row) {
    processRow($row); // only one row in memory at a time
}

References

• ↗ https://www.php.net/manual/en/language.generators.php

Tags

Related Terms