Generators provide an easy way to implement simple iterators without the overhead or complexity of implementing a class that implements the Iterator interface. A generator offers a convenient way to provide data to &foreach; loops without having to build an array in memory ahead of time, which may cause the program to exceed a memory limit or require a considerable amount of processing time to generate. Instead, a generator function can be used, which is the same as a normal function, except that instead of returning once, a generator can &yield; as many times as it needs to in order to provide the values to be iterated over. Like with iterators, random data access is not possible. A simple example of this is to reimplement the range function as a generator. The standard range function has to generate an array with every value in it and return it, which can result in large arrays: for example, calling range(0, 1000000) will result in well over 100 MB of memory being used. As an alternative, we can implement an xrange() generator, which will only ever need enough memory to create an Iterator object and track the current state of the generator internally, which turns out to be less than 1 kilobyte. = 0) { throw new LogicException('Step must be negative'); } for ($i = $start; $i >= $limit; $i += $step) { yield $i; } } } /* * Note that both range() and xrange() result in the same * output below. */ echo 'Single digit odd numbers from range(): '; foreach (range(1, 9, 2) as $number) { echo "$number "; } echo "\n"; echo 'Single digit odd numbers from xrange(): '; foreach (xrange(1, 9, 2) as $number) { echo "$number "; } ?> ]]> &example.outputs; When a generator function is called, a new object of the internal Generator class is returned. This object implements the Iterator interface in much the same way as a forward-only iterator object would, and provides methods that can be called to manipulate the state of the generator, including sending values to and returning values from it. A generator function looks just like a normal function, except that instead of returning a value, a generator &yield;s 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. A generator can return values, which can be retrieved using Generator::getReturn. 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. ]]> &example.outputs; Internally, sequential integer keys will be paired with the yielded values, just as with a non-associative array. PHP 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. $fields; } } foreach (input_parser($input) as $id => $fields) { echo "$id:\n"; echo " $fields[0]\n"; echo " $fields[1]\n"; } ?> ]]> &example.outputs; Yield can be called without an argument to yield a &null; value with an automatic key. ]]> &example.outputs; NULL [1]=> NULL [2]=> NULL } ]]> 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. 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).'... '; } ?> ]]> &example.outputs; 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 preserve_keys which can be set to &false; to collect all the values while ignoring the keys returned by the Generator. ]]> &example.outputs; int(1) [1]=> int(4) [2]=> int(3) } ]]> ]]> &example.outputs; getReturn(); ?> ]]> &example.outputs; The primary advantage of generators is their simplicity. Much less boilerplate code has to be written compared to implementing an Iterator class, and the code is generally much more readable. For example, the following function and class are equivalent: fileHandle = fopen($fileName, 'r')) { throw new RuntimeException('Couldn\'t open file "' . $fileName . '"'); } } public function rewind() { fseek($this->fileHandle, 0); $this->line = fgets($this->fileHandle); $this->i = 0; } public function valid() { return false !== $this->line; } public function current() { return $this->line; } public function key() { return $this->i; } public function next() { if (false !== $this->line) { $this->line = fgets($this->fileHandle); $this->i++; } } public function __destruct() { fclose($this->fileHandle); } } ?> ]]> This flexibility does come at a cost, however: generators are forward-only iterators, and cannot be rewound once iteration has started. This also means that the same generator can't be iterated over multiple times: the generator will need to be rebuilt by calling the generator function again. &reftitle.seealso; Object Iteration