Generator syntaxA 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. Any function containing yield is a generator function. 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 object's iteration methods 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 can simply return, and the calling code continues just as if an array has run out of values.
yield keywordThe 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. Example #1 A simple example of yielding values
The above example will output: 1 2 3
Yielding values with keysPHP also supports associative arrays, and generators are no different. In addition to yielding simple values, as shown above, you can also yield a key at the same time. The syntax for yielding a key/value pair is very similar to that used to define an associative array, as shown below. Example #2 Yielding a key/value pair
The above example will output: 1: PHP Likes dollar signs 2: Python Likes whitespace 3: Ruby Likes blocks Yielding null values
Yield can be called without an argument to yield a Example #3 Yielding
The above example will output: array(3) { [0]=> NULL [1]=> NULL [2]=> NULL } Yielding by referenceGenerator 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
The above example will output: 2... 1... 0... Generator delegation via yield fromGenerator 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. Caution
Storing into an array (e.g. with iterator_to_array)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
Example #5 yield from with iterator_to_array
The above example will output: array(3) { [0]=> int(1) [1]=> int(4) [2]=> int(3) } Example #6 Basic use of yield from
The above example will output: 1 2 3 4 5 6 7 8 9 10 Example #7 yield from and return values
The above example will output: 1 2 3 4 5 6 7 8 9 10 |