PHP Iterables

PHP Iterables and Generators: Streaming Collections with yield

In PHP, iterable is a built-in union type (array|Traversable) that accepts any collection you can loop over with foreach. Pairing iterable parameters with PHP generators (yield) lets your code stream millions of rows while holding only one record in memory at a time.

Accepting iterable in Function Signatures

Typing a parameter as iterable makes helper functions flexible: callers can pass a plain PHP array today or switch to a lazy Generator or ArrayObject tomorrow without changing your function signature.

<?php
declare(strict_types=1);

function printReportRows(iterable $rows): void
{
    foreach ($rows as $index => $row) {
        echo ($index + 1) . ". {$row}" . PHP_EOL;
    }
}

function generateSequence(int $limit): Generator
{
    for ($i = 1; $i <= $limit; $i++) {
        yield "Invoice #100{$i}";
    }
}

printReportRows(['Summary Header', 'Tax Breakdown']);
printReportRows(generateSequence(3));

Why Generators Save Memory on Large Datasets

When a function builds and returns a large array, PHP allocates memory for every element up front. A generator function pauses execution at each yield, hands one value to the foreach loop, and resumes only when the loop asks for the next item.

Common Mistakes to Avoid

• Calling count() or array_map() directly on an iterable: count() fails on plain Generator objects because generators do not implement Countable and have unknown length until exhausted.
• Looping over the same Generator twice: Generators are single-pass streams. Looping a second time throws an Exception: Cannot traverse an already closed generator.
• Mixing return values carelessly: A generator's return value is retrieved via $gen->getReturn() after iteration finishes, not yielded into foreach.

Frequently Asked Questions

Can a PHP generator yield both keys and values?

Yes. Write yield $key => $value; inside the generator and read both in foreach ($gen as $key => $value).

What is yield from used for?

yield from $otherIterable delegates yielding directly to another array or nested generator without writing an extra inner foreach loop.

How do I convert an iterable to an array if I really need array functions?

Use iterator_to_array($items) when $items instanceof Traversable, or simply check is_array($items) ? $items : iterator_to_array($items).