Les générateurs fournissent une façon simple de mettre en place des itérateurs sans le coût ni la complexité du développement d'une classe qui implémente l'interface Iterator. Un générateur offre un moyen pratique de fournir des données aux boucles &foreach; sans avoir à construire un tableau en mémoire à l'avance, ce qui pourrait amener le programme à dépasser une limite de mémoire ou nécessiter un temps de traitement considérable pour les générer. À la place, une fonction générateur peut être utilisée, qui est identique à une fonction normale, mis à part le fait qu'au lieu de retourner une seule fois, un générateur peut utiliser &yield; autant de fois que nécessaire, afin de fournir les valeurs à parcourir. Comme avec les itérateurs, l'accès aléatoire aux données n'est pas possible. Un exemple simple de ce mécanisme est la ré-implémentation de la fonction range sous la forme d'un générateur. La fonction standard range doit générer un tableau contenant chaque valeur, et le retourner, ce qui peut conduire à des tableaux de taille importante : par exemple, l'appel du code range(0, 1000000) peut consommer nettement plus de 100 Mo de mémoire. Comme alternative, nous pouvons implémenter un générateur xrange(), qui n'aura comme besoin mémoire que la seule création d'un objet Iterator, et devra garder trace en interne du statut courant du générateur, ce qui revient à une consommation mémoire inférieure à 1 Ko. = 0) { throw new LogicException('Step must be negative'); } for ($i = $start; $i >= $limit; $i += $step) { yield $i; } } } /* * Il est à noter que les fonctions range() et xrange() produisent le * même affichage, ci-dessous. */ echo 'Nombres impairs à un seul chiffre depuis range() : '; foreach (range(1, 9, 2) as $number) { echo "$number "; } echo "\n"; echo 'Nombres impairs à un seul chiffre depuis xrange() : '; foreach (xrange(1, 9, 2) as $number) { echo "$number "; } ?> ]]> &example.outputs; Lorsqu'une fonction générateur est appelée, un objet de la classe interne Generator est retourné. Cet objet implémente l'interface Iterator de la même façon qu'un objet itérateur, qui avance uniquement, le ferait, et fournit les méthodes qui peuvent être appelées pour manipuler le statut du générateur, y compris l'envoi des valeurs et leurs retours. 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. 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. ]]> &example.outputs; 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. 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 : $fields; } } foreach (input_parser($input) as $id => $fields) { echo "$id:\n"; echo " $fields[0]\n"; echo " $fields[1]\n"; } ?> ]]> &example.outputs; Yield peut être appelé sans argument pour fournir une valeur nulle avec une clé automatique. ]]> &example.outputs; 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. 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).'... '; } ?> ]]> &example.outputs; 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. 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. ]]> &example.outputs; int(1) [1]=> int(4) [2]=> int(3) } ]]> ]]> &example.outputs; getReturn(); ?> ]]> &example.outputs; Le principal avantage des générateurs est leur simplicité. Moins de code doit être écrit que lorsqu'il s'agit d'implémenter une classe Iterator, et il est généralement plus lisible. Par exemple, la fonction et la classe suivante sont équivalentes : fileHandle = fopen($fileName, 'r')) { throw new RuntimeException('Impossible d\'ouvrir le fichier : "' . $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); } } ?> ]]> Cependant, cette flexibilité a un coût : les générateurs sont des itérateurs n'allant que vers l'avant, et ils ne peuvent pas être ré-initialisés une fois leur parcours commencé. Cela signifie également que le même générateur ne peut pas être utilisé à plusieurs reprises : le générateur devra être reconstruit en appelant une nouvelle fois la fonction générateur. &reftitle.seealso; Itération d'Objet