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. 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.
Note:
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 #1 A simple example of yielding values
<?php
function gen_one_to_three() {
for ($i = 1; $i <= 3; $i++) {
// Note that $i is preserved between yields.
yield $i;
}
}
$generator = gen_one_to_three();
foreach ($generator as $value) {
echo "$value\n";
}
?>The above example will output:
1 2 3
Note:
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.
Example #2 Yielding a key/value pair
<?php
/*
* The input is semi-colon separated fields, with the first
* field being an ID to use as a key.
*/
$input = <<<'EOF'
1;PHP;Likes dollar signs
2;Python;Likes whitespace
3;Ruby;Likes blocks
EOF;
function input_parser($input) {
foreach (explode("\n", $input) as $line) {
$fields = explode(';', $line);
$id = array_shift($fields);
yield $id => $fields;
}
}
foreach (input_parser($input) as $id => $fields) {
echo "$id:\n";
echo " $fields[0]\n";
echo " $fields[1]\n";
}
?>The above example will output:
1:
PHP
Likes dollar signs
2:
Python
Likes whitespace
3:
Ruby
Likes blocks
Yield can be called without an argument to yield a null value with an
automatic key.
Example #3 Yielding nulls
<?php
function gen_three_nulls() {
foreach (range(1, 3) as $i) {
yield;
}
}
var_dump(iterator_to_array(gen_three_nulls()));
?>The above example will output:
array(3) {
[0]=>
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.
Example #4 Yielding values by reference
<?php
function &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 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 #5 yield from with iterator_to_array()
<?php
function inner() {
yield 1; // key 0
yield 2; // key 1
yield 3; // key 2
}
function gen() {
yield 0; // key 0
yield from inner(); // keys 0-2
yield 4; // key 1
}
// pass false as second parameter to get an array [0, 1, 2, 3, 4]
var_dump(iterator_to_array(gen()));
?>The above example will output:
array(3) {
[0]=>
int(1)
[1]=>
int(4)
[2]=>
int(3)
}
Example #6 Basic use of yield from
<?php
function count_to_ten() {
yield 1;
yield 2;
yield from [3, 4];
yield from new ArrayIterator([5, 6]);
yield from seven_eight();
yield 9;
yield 10;
}
function seven_eight() {
yield 7;
yield from eight();
}
function eight() {
yield 8;
}
foreach (count_to_ten() as $num) {
echo "$num ";
}
?>The above example will output:
1 2 3 4 5 6 7 8 9 10
Example #7 yield from and return values
<?php
function count_to_ten() {
yield 1;
yield 2;
yield from [3, 4];
yield from new ArrayIterator([5, 6]);
yield from seven_eight();
return yield from nine_ten();
}
function seven_eight() {
yield 7;
yield from eight();
}
function eight() {
yield 8;
}
function nine_ten() {
yield 9;
return 10;
}
$gen = count_to_ten();
foreach ($gen as $num) {
echo "$num ";
}
echo $gen->getReturn();
?>The above example will output:
1 2 3 4 5 6 7 8 9 10
For example yield keyword with Fibonacci:
function getFibonacci()
{
$i = 0;
$k = 1; //first fibonacci value
yield $k;
while(true)
{
$k = $i + $k;
$i = $k - $i;
yield $k;
}
}
$y = 0;
foreach(getFibonacci() as $fibonacci)
{
echo $fibonacci . "\n";
$y++;
if($y > 30)
{
break; // infinite loop prevent
}
}[This comment replaces my previous comment]
You can use generators to do lazy loading of lists. You only compute the items that are actually used. However, when you want to load more items, how to cache the ones already loaded?
Here is how to do cached lazy loading with a generator:
<?php
class CachedGenerator {
protected $cache = [];
protected $generator = null;
public function __construct($generator) {
$this->generator = $generator;
}
public function generator() {
foreach($this->cache as $item) yield $item;
while( $this->generator->valid() ) {
$this->cache[] = $current = $this->generator->current();
$this->generator->next();
yield $current;
}
}
}
class Foobar {
protected $loader = null;
protected function loadItems() {
foreach(range(0,10) as $i) {
usleep(200000);
yield $i;
}
}
public function getItems() {
$this->loader = $this->loader ?: new CachedGenerator($this->loadItems());
return $this->loader->generator();
}
}
$f = new Foobar;
# First
print "First\n";
foreach($f->getItems() as $i) {
print $i . "\n";
if( $i == 5 ) {
break;
}
}
# Second (items 1-5 are cached, 6-10 are loaded)
print "Second\n";
foreach($f->getItems() as $i) {
print $i . "\n";
}
# Third (all items are cached and returned instantly)
print "Third\n";
foreach($f->getItems() as $i) {
print $i . "\n";
}
?>If for some strange reason you need a generator that doesn't yield anything, an empty function doesn't work; the function needs a yield statement to be recognised as a generator.
<?php
function gndn()
{
}
foreach(gndn() as $it)
{
echo 'FNORD';
}
?>
But it's enough to have the yield syntactically present even if it's not reachable:
<?php
function gndn()
{
if(false) { yield; }
}
foreach(gndn() as $it)
{
echo 'FNORD';
}
?>Do not call generator functions directly, that won't work.
<?php
function my_transform($value) {
var_dump($value);
return $value * 2;
}
function my_function(array $values) {
foreach ($values as $value) {
yield my_transform($value);
}
}
$data = [1, 5, 10];
// my_transform() won't be called inside my_function()
my_function($data);
# my_transform() will be called.
foreach (my_function($data) as $val) {
// ...
}
?>That is a simple fibonacci generator.
<?php
function fibonacci($item) {
$a = 0;
$b = 1;
for ($i = 0; $i < $item; $i++) {
yield $a;
$a = $b - $a;
$b = $a + $b;
}
}
# give me the first ten fibonacci numbers
$fibo = fibonacci(10);
foreach ($fibo as $value) {
echo "$value\n";
}
?><?php
//Example of class implementing IteratorAggregate using generator
class ValueCollection implements IteratorAggregate
{
private $items = array();
public function addValue($item)
{
$this->items[] = $item;
return $this;
}
public function getIterator()
{
foreach ($this->items as $item) {
yield $item;
}
}
}
//Initializes a collection
$collection = new ValueCollection();
$collection
->addValue('A string')
->addValue(new stdClass())
->addValue(NULL);
foreach ($collection as $item) {
var_dump($item);
}This is little example of using generators with recursion. Used version of php is 5.5.5
[php]
<?php
define ("DS", DIRECTORY_SEPARATOR);
define ("ZERO_DEPTH", 0);
define ("DEPTHLESS", -1);
define ("OPEN_SUCCESS", True);
define ("END_OF_LIST", False);
define ("CURRENT_DIR", ".");
define ("PARENT_DIR", "..");
function DirTreeTraversal($DirName, $MaxDepth = DEPTHLESS, $CurrDepth = ZERO_DEPTH)
{
if (($MaxDepth === DEPTHLESS) || ($CurrDepth < $MaxDepth)) {
$DirHandle = opendir($DirName);
if ($DirHandle !== OPEN_SUCCESS) {
try{
while (($FileName = readdir($DirHandle)) !== END_OF_LIST) { //read all file in directory
if (($FileName != CURRENT_DIR) && ($FileName != PARENT_DIR)) {
$FullName = $DirName.$FileName;
yield $FullName;
if(is_dir($FullName)) { //include sub files and directories
$SubTrav = DirTreeTraversal($FullName.DS, $MaxDepth, ($CurrDepth + 1));
foreach($SubTrav as $SubItem) yield $SubItem;
}
}
}
} finally {
closedir($DirHandle);
}
}
}
}
$PathTrav = DirTreeTraversal("C:".DS, 2);
print "<pre>";
foreach($PathTrav as $FileName) printf("%s\n", $FileName);
print "</pre>";
[/php]If you mix yielding values with keys and yielding values without keys, the result is the same as adding values to an array with or without keys.
<?php
function gen() {
yield 'a';
yield 4 => 'b';
yield 'c';
}
$t = iterator_to_array(gen());
var_dump($t);
?>
The result is an array [0 => 'a', 4 => 'b', 5 => 'c'], just as if you had written
<?php
$t = [];
$t[] = 'a';
$t[4] = 'b';
$t[] = 'c';
var_dump($t);
?>
With the key given to 'c' being incremented from the previous numeric index.Module list of a number from 1 to 100.
<?php
function list_of_modulo(){
for($i = 1; $i <= 100; $i++){
if(($i % 2) == 0){
yield $i;
}
}
}
$modulos = list_of_modulo();
foreach($modulos as $value){
echo "$value\n";
}
?>