Syntaxe d'un Générateur

Une fonction générateur ressemble à une fonction normale, sauf qu'au lieu de retourner une valeur, un générateur yield retourne autant de valeurs que nécessaire. Toute fonction contenant yield est une fonction générateur.

Lorsqu'une fonction gĂ©nĂ©rateur est appelĂ©e, elle retourne un objet que l'on peut parcourir. Lors du parcours de cet objet (par exemple, via une boucle foreach), PHP appellera les mĂ©thodes d'itĂ©ration de l'objet chaque fois qu'il a besoin d'une valeur, puis sauvegarde le statut du gĂ©nĂ©rateur lorsqu'il gĂ©nĂšre une valeur, pour qu'il puisse ĂȘtre repris lorsque la prochaine valeur sera requise.

Lorsqu'il n'y a plus de valeur à fournir, la fonction générateur peut simplement retourner, et le code appelant continuera comme si un tableau n'avait plus de valeur.

Note:

Un gĂ©nĂ©rateur peut retourner des valeurs, qui peuvent ĂȘtre rĂ©cupĂ©rĂ©es en utilisant Generator::getReturn().

Le mot-clé yield

Le mot clĂ© yield est le cƓur d'une fonction gĂ©nĂ©rateur. Dans sa forme la plus simple, une instruction yield ressemble Ă  une instruction return, exceptĂ© qu'au lieu de stopper l'exĂ©cution de la fonction et de retourner, yield fournit une valeur au code parcourant le gĂ©nĂ©rateur, et met en pause l'exĂ©cution de la fonction gĂ©nĂ©rateur.

Exemple #1 Un exemple simple de production de valeurs

<?php
function gen_one_to_three() {
for (
$i = 1; $i <= 3; $i++) {
// $i est préservé entre chaque production de valeur.
yield $i;
}
}

$generator = gen_one_to_three();
foreach (
$generator as $value) {
echo
"$value\n";
}

L'exemple ci-dessus va afficher :

1
2
3

Note:

En interne, des clĂ©s sĂ©quentielles entiĂšres seront associĂ©es avec les valeurs produites, de la mĂȘme maniĂšre que pour un tableau non-associatif.

Fourniture de valeurs avec des clés

PHP supporte Ă©galement les tableaux associatifs, et les gĂ©nĂ©rateurs ne sont pas diffĂ©rents. En plus de fournir des valeurs simples, comme nous l'avons vu plus haut, il est aussi possible, en mĂȘme temps, de fournir une clĂ©.

La syntaxe permettant de produire une paire clé/valeur est similaire à celle utilisée pour définir un tableau associatif ; comme ceci :

Exemple #2 Production d'une paire clé/valeur

<?php
/*
* L'entrée est constituée de champs séparés par un point-virgule,
* et le premier champ est un ID à utiliser comme clé.
*/

$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";
}

L'exemple ci-dessus va afficher :

1:
    PHP
    Likes dollar signs
2:
    Python
    Likes whitespace
3:
    Ruby
    Likes blocks

Production de valeurs nulles

Yield peut ĂȘtre appelĂ© sans argument pour fournir une valeur nulle avec une clĂ© automatique.

Exemple #3 Production de valeurs nulles

<?php
function gen_three_nulls() {
foreach (
range(1, 3) as $i) {
yield;
}
}

var_dump(iterator_to_array(gen_three_nulls()));

L'exemple ci-dessus va afficher :

array(3) {
  [0]=>
  NULL
  [1]=>
  NULL
  [2]=>
  NULL
}

Production de valeurs par référence

Les fonctions gĂ©nĂ©rateur peuvent produire des valeurs par rĂ©fĂ©rence. Ceci se fait de la mĂȘme façon que le retour par rĂ©fĂ©rence depuis des fonctions : en ajoutant un ET commercial (&) au nom de la fonction.

Exemple #4 Production de valeurs par référence

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

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

/*
* Il est Ă  noter qu'il est possible de changer $number dans la boucle,
* et, du fait que le générateur fournit des références, $value
* dans gen_reference() change aussi.
*/
foreach (gen_reference() as &$number) {
echo (--
$number).'... ';
}

L'exemple ci-dessus va afficher :

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

Délégation du générateur via yield from

La délégation du générateur permet d'obtenir les valeurs d'un autre générateur, d'un objet Traversable, ou d'un array en utilisant le mot clé yield from. Le générateur externe va ainsi obtenir toutes les valeurs du générateur interne, de l'objet, ou du tableau tant qu'il n'est pas invalide, aprÚs quoi, l'exécution va continuer dans le générateur externe.

Si un générateur est utilisé avec l'expression yield from, l'expression yield from va aussi retourner toute valeur retournée par le générateur interne.

Attention

Stocker dans un tableau (e.g. avec iterator_to_array())

yield from ne réinitialise pas les clés. Il préserve les clés retournées par l'objet Traversable, ou array. Donc, certaines valeurs peuvent partager une clé commune avec d'autres yield ou yield from, qui, lors de l'insertion dans un tableau, écrasera les anciennes valeurs avec cette clé.

Un cas frĂ©quent oĂč cela est important est iterator_to_array() renvoyant un tableau avec clĂ© par dĂ©faut, conduisant Ă  des rĂ©sultats Ă©ventuellement inattendus. iterator_to_array() a un second paramĂštre preserve_keys qui peut ĂȘtre dĂ©fini sur false pour collecter toutes les valeurs en ignorant les clĂ©s renvoyĂ©es par le Generator.

Exemple #5 yield from avec iterator_to_array()

<?php
function inner() {
yield
1; // clé 0
yield 2; // clé 1
yield 3; // clé 2
}
function
gen() {
yield
0; // clé 0
yield from inner(); // clés 0-2
yield 4; // clé 1
}
// met Ă  false le second paramĂštre pour avoir un tableau [0, 1, 2, 3, 4]
var_dump(iterator_to_array(gen()));

L'exemple ci-dessus va afficher :

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(4)
  [2]=>
  int(3)
}

Exemple #6 Utilisation basique de 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 ";
}

L'exemple ci-dessus va afficher :

1 2 3 4 5 6 7 8 9 10 

Exemple #7 yield from et les valeurs retournées

<?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();

L'exemple ci-dessus va afficher :

1 2 3 4 5 6 7 8 9 10
add a note

User Contributed Notes 9 notes

up
128
Adil lhan (adilmedya at gmail dot com) ¶
13 years ago
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
    }
}
up
50
info at boukeversteegh dot nl ¶
11 years ago
[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";
}
?>
up
22
Hayley Watson ¶
10 years ago
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';
}

?>
up
13
zilvinas at kuusas dot lt ¶
10 years ago
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) {
    // ...
}
?>
up
11
christophe dot maymard at gmail dot com ¶
11 years ago
<?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);
}
up
12
Harun Yasar harunyasar at mail dot com ¶
10 years ago
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";
}
?>
up
8
Shumeyko Dmitriy ¶
12 years ago
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]
up
0
harl at gmail dot com ¶
1 year ago
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.
up
-1
christianggimenez at gmail dot com ¶
6 years ago
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";
}

?>