Skip to content
Tutorials Center
My learning

Topics

Lesson 103 of 147 ยท Advanced PHP

Generators

Learn PHP generators - how yield pauses a function, keys, lazy pipelines for large files, yield from, sending values in, return values and the memory savings.

A normal function runs from top to bottom and hands back one value. A generator is a function that can hand back many values, one at a time, pausing after each one until you ask for the next. You write it like a regular function, but with yield instead of (or in addition to) return, and you loop over it with foreach just like an array.

Why bother? Because a generator produces values lazily. An array of a million rows has to exist in memory all at once; a generator that produces a million rows only ever holds one. That makes generators the natural tool for reading big files line by line, streaming database results, building data pipelines and describing infinite sequences. They're also the foundation for the iterator ideas in the next lesson, Iterators and the SPL.

Your first generator

Any function that contains the yield keyword is a generator function. Calling it doesn't run its body. Instead, PHP returns a Generator object, and the body runs bit by bit as you iterate:

PHP yield pauses the function

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Read the output carefully, because it shows exactly how a generator works:

  1. countdown(3) returns immediately. [starting] is not printed until the loop begins.
  2. The loop asks for the first value. The function runs until it reaches yield 3, hands 3 to the loop and freezes right there, with all its local variables intact.
  3. The loop body runs, then asks for the next value. The function resumes after the yield, prints [resumed after 3], loops, and yields 2.
  4. After the last value, the function runs to its end, prints [finished], and the loop stops.

The return type is Generator (you can also write iterable or Iterator, which Generator implements). Declaring it documents that the function is lazy.

Keys and values

A generator yields keys too. By default the keys are 0, 1, 2, ..., just like a list. Use yield $key => $value to choose your own:

PHP Yielding keys

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Keys can be any type, even arrays or objects, and they can repeat. That's fine for foreach, but watch out when you convert a generator to an array with iterator_to_array(): duplicate keys overwrite each other unless you pass preserve_keys: false.

Infinite sequences

Because values are made on demand, a generator can describe a sequence that never ends. The loop that consumes it decides when to stop:

PHP An endless Fibonacci generator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

while (true) inside a generator is perfectly safe: the function pauses at every yield, so it only computes as many numbers as the caller asks for. A plain return; inside a generator ends it early, as take() does when the limit is reached.

Never call iterator_to_array() (or spread ...) on an infinite generator. It tries to collect every value and runs until it hits the memory limit.

Generators for large data

The classic use is processing a file too big to load at once. file() and file_get_contents() read everything into memory; a generator that wraps fgets() reads one line at a time. Then you can chain small generators into a pipeline, where each stage transforms values as they flow through:

PHP A lazy pipeline over a log file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The three stages never build an intermediate array. One line is read, parsed into an array, checked and counted; only then is the next line read. The same code works for a 2 KB file or a 20 GB file, with the same small memory footprint.

The try/finally in readLines() matters. If the consumer breaks out of its loop early, the generator is destroyed while paused, and PHP runs its finally blocks, so the file is still closed.

Measuring the difference

To see the memory savings directly, compare building an array of 200,000 numbers with yielding them:

PHP Array versus generator memory

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The array version needs about 4 MB, because all 200,000 integers exist at once. The generator needs about 1 KB, and that stays the same no matter how large the count gets. (memory_reset_peak_usage() was added in PHP 8.2 and makes this kind of measurement easy; see Performance and OPcache for more measuring tools.)

The trade-off: a generator can only be iterated once, and only forward. You can't count() it, index it with [3] or loop over it twice. If you need those, collect the values into an array or call the generator function again.

PHP A generator runs only once

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

yield from: delegating to another generator

yield from passes along every value from another generator, array or iterator, as if the current generator had yielded them itself. It's how you compose generators and how you write recursive ones neatly:

PHP yield from and recursion

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Notice the csv() keys if you ever convert it with iterator_to_array(): yield from keeps the inner generator's keys, so csvHeader() and csvRows() both start at key 0 and would overwrite each other. Pass preserve_keys: false in that case. The recursive paths() shows how recursion and generators fit together: each level yields its own path, then delegates the subtree to a recursive call.

Sending values into a generator

Generators are two-way. yield is also an expression: when the caller resumes the generator with $gen->send($value), that value becomes the result of the paused yield. This turns a generator into a small stateful worker, sometimes called a coroutine:

PHP send() and getReturn()

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The important methods of Generator:

Method What it does
current() Runs to the first yield if needed and returns the current value
key() Returns the current key
next() Resumes the generator until the next yield
send($value) Resumes it, making $value the result of the paused yield, and returns the next yielded value
valid() false once the generator has finished
getReturn() The value from return, available only after the generator finishes
throw($exception) Throws the exception at the paused yield, inside the generator

send() first runs the generator to its first yield if it hasn't started, so the explicit current() call above isn't strictly required. It's there to make the flow obvious: the first yield produces null (no average yet) before any value has been sent.

Sending values is a powerful but niche feature. In everyday code you'll mostly use plain yield and yield from. Two-way generators were how PHP async libraries worked before Fibers arrived in PHP 8.1, which made that style mostly unnecessary.

Generators versus arrays: when to use which

Use a generator when:

  • The data is large or comes from a stream (files, database cursors, API pages).
  • You may not need every value (search until found, take the first N).
  • The sequence is infinite or expensive to compute.
  • You want composable pipeline stages.

Use an array when:

  • You need to count, sort, index, or loop more than once.
  • The data is small; an array is simpler and a little faster to iterate.
  • You need array functions like array_map() or usort(), which accept only arrays. (iterator_to_array() bridges the two.)

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does calling a generator function, like $g = countdown(3);, do?

    Calling a generator function only creates the Generator object. The body starts running when you begin iterating, for example in foreach or with current().
  2. 2. A generator yields "x" => 1 and then "x" => 2. What does iterator_to_array($gen) return?

    With preserved keys, the second value overwrites the first under the same key. Pass preserve_keys false to get a list [1, 2].
  3. 3. Why does a pipeline of generators use little memory when reading a huge file?

    Every stage pulls one value at a time from the previous one, so only the current line and its derived values exist in memory.
  4. 4. What happens if you loop over the same Generator object a second time after it finished?

    Generators are forward-only and single-use. Call the generator function again to get a fresh one.
  5. 5. Inside a generator, $x = yield 5; runs and the caller then calls $gen->send(10). What is $x?

    The yield expression evaluates to the value passed to send(). The 5 is what the generator handed out; 10 is what came back in.

Summary

  • A function containing yield is a generator function. Calling it returns a Generator object; the body runs step by step as you iterate.
  • Each yield hands out a value and pauses the function with its state intact. yield $key => $value sets keys, which may be any type and may repeat.
  • Generators are lazy: they can describe infinite sequences and process huge files with constant memory. Chain small generators into pipelines.
  • A generator can be iterated once, forward only. Use iterator_to_array() (watch duplicate keys) when you need an array.
  • yield from delegates to another generator, array or iterator, which makes composition and recursive generators easy.
  • send() passes a value back in as the result of yield; return sets a value you read with getReturn().
  • finally blocks run even when the consumer stops early, so use them to close files and connections.

Next: Iterators and the SPL