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. Toutes fonctions 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. Lorsque vous parcourez 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 sortir, et le code appelant continuera comme si un tableau n'avait plus de valeur.
Note:
Dans PHP 5, un générateur ne devrait pas retourner de valeur : si vous tentez de retourner une valeur depuis un générateur, une erreur de compilation pourrait être émise. Une structure return vide etait une syntaxe valide dans un générateur et aurait fait terminer le générateur. Depuis PHP 7.0, un générateur peut retourner des valeurs, qui peuvent être récupérées en utilisant Generator::getReturn().
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++) {
// Notez que $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.
Si vous utilisez yield dans un contexte d'expression (par exemple, à droite d'un assignement), vous devez entourer l'instruction yield avec des parenthèses en PHP 5. Par exemple, ceci est valide :
$data = (yield $value);
Mais ceci ne l'est pas, et entrainera une erreur d'analyse en PHP 5 :
$data = yield $value;
Les restrictions sur les parenthèses ne sont pas appliquées en PHP 7.
La valeur qui sera affectée à $data est la valeur passée
à Generator::send()ou NULL si
Generator::next() est appelé à la place.
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, vous pouvez aussi, en même temps, 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
Comme dans le cas de production de valeurs simples, la fourniture d'une paire clé/valeur dans un contexte d'expression requiert que la structure yield soit entre parenthèses :
$data = (yield $key => $value);
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
}
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;
}
}
/*
* Notez 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...
En PHP 7, la délégation du générateur vous 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.
yield from ne réinitialise pas les clés. Il préseve 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
use_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