Generator syntax

A generator function looks just like a normal function, except that instead
of returning a value, a generator yields as many values as it needs to.

When a generator function is called, it returns an object that can be
iterated over. When you iterate over that object (for instance, via a
foreach loop), PHP will call the generator function each time it needs a
value, then saves the state of the generator when the generator yields a
value so that it can be resumed when the next value is required.

Once there are no more values to be yielded, then the generator function
can simply exit, and the calling code continues just as if an array has run
out of values.

Note:

In PHP 5, a generator could not return a value: doing so would result in a compile
error. An empty return statement was valid syntax within
a generator and it would terminate the generator. Since PHP 7.0, a generator can
return values, which can be retrieved using Generator::getReturn().

yield keyword

The heart of a generator function is the yield keyword.
In its simplest form, a yield statement looks much like a return
statement, except that instead of stopping execution of the function and
returning, yield instead provides a value to the code looping over the
generator and pauses execution of the generator function.

Yielding by reference

Generator functions are able to yield values by reference as well as by
value. This is done in the same way as
returning references from functions:
by prepending an ampersand to the function name.

Example #4 Yielding values by reference

<?phpfunction &gen_reference() {$value = 3;

while ($value > 0) {yield $value; }}

/* * Note that we can change $number within the loop, and * because the generator is yielding references, $value * within gen_reference() changes. */foreach (gen_reference() as &$number) { echo (--$number).'... ';}?>

The above example will output:

2... 1... 0...

Generator delegation via yield from

In PHP 7, generator delegation allows you to yield values from another
generator, Traversable object, or
array by using the yield from keyword.
The outer generator will then yield all values from the inner generator,
object, or array until that is no longer valid, after which execution
will continue in the outer generator.

If a generator is used with yield from, the
yield from expression will also return any value
returned by the inner generator.

yield from does not reset the keys. It preserves
the keys returned by the Traversable object, or
array. Thus some values may share a common key with another
yield or yield from, which, upon
insertion into an array, will overwrite former values with that key.

A common case where this matters is iterator_to_array()
returning a keyed array by default, leading to possibly unexpected results.
iterator_to_array() has a second parameter
use_keys which can be set to FALSE to collect
all the values while ignoring the keys returned by the Generator.