<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Generator syntax</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="language.generators.overview.html">Generators overview</a></div>
<div class="next" style="text-align: right; float: right;"><a href="language.generators.comparison.html">Comparing generators with Iterator objects</a></div>
<div class="up"><a href="language.generators.html">Generators</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="language.generators.syntax" class="sect1">
<h2 class="title">Generator syntax</h2>
<p class="para">
A generator function looks just like a normal function, except that instead
of returning a value, a generator <a href="language.generators.syntax.html#control-structures.yield" class="link">yield</a>s as many values as it needs to.
</p>
<p class="para">
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
<a href="control-structures.foreach.html" class="link">foreach</a> loop), PHP will call the generator function 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.
</p>
<p class="para">
Once there are no more values to be yielded, then the generator function
can simply exit, and the calling code continues just as if an array has run
out of values.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
A generator cannot return a value: doing so will result in a compile
error. An empty <strong class="command">return</strong> statement is valid syntax within
a generator and it will terminate the generator.
</p>
</p></blockquote>
<div class="sect2" id="control-structures.yield">
<h3 class="title"><strong class="command">yield</strong> keyword</h3>
<p class="para">
The heart of a generator function is the <strong class="command">yield</strong> 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.
</p>
<div class="example" id="example-275">
<p><strong>Example #1 A simple example of yielding values</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">gen_one_to_three</span><span style="color: #007700">() {<br /> for (</span><span style="color: #0000BB">$i </span><span style="color: #007700">= </span><span style="color: #0000BB">1</span><span style="color: #007700">; </span><span style="color: #0000BB">$i </span><span style="color: #007700"><= </span><span style="color: #0000BB">3</span><span style="color: #007700">; </span><span style="color: #0000BB">$i</span><span style="color: #007700">++) {<br /> </span><span style="color: #FF8000">// Note that $i is preserved between yields.<br /> </span><span style="color: #0000BB">yield $i</span><span style="color: #007700">;<br /> }<br />}<br /><br /></span><span style="color: #0000BB">$generator </span><span style="color: #007700">= </span><span style="color: #0000BB">gen_one_to_three</span><span style="color: #007700">();<br />foreach (</span><span style="color: #0000BB">$generator </span><span style="color: #007700">as </span><span style="color: #0000BB">$value</span><span style="color: #007700">) {<br /> echo </span><span style="color: #DD0000">"</span><span style="color: #0000BB">$value</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
1
2
3
</pre></div>
</div>
</div>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
Internally, sequential integer keys will be paired with the yielded
values, just as with a non-associative array.
</p>
</p></blockquote>
<div class="caution"><strong class="caution">Caution</strong>
<p class="para">
If you use yield in an expression context (for example, on the right hand
side of an assignment), you must surround the yield statement with
parentheses. For example, this is valid:
</p>
<div class="informalexample">
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
$data = (yield $value);</span>
</code></div>
</div>
</div>
<p class="para">
But this is not, and will result in a parse error:
</p>
<div class="informalexample">
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
$data = yield $value;</span>
</code></div>
</div>
</div>
<p class="para">
This syntax may be used in conjunction with the
<span class="methodname"><a href="generator.send.html" class="methodname">Generator::send()</a></span> method.
</p>
</div>
<div class="sect3" id="control-structures.yield.associative">
<h4 class="title">Yielding values with keys</h4>
<p class="para">
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.
</p>
<p class="para">
The syntax for yielding a key/value pair is very similar to that used to
define an associative array, as shown below.
</p>
<div class="example" id="example-276">
<p><strong>Example #2 Yielding a key/value pair</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/*<br /> * The input is semi-colon separated fields, with the first<br /> * field being an ID to use as a key.<br /> */<br /><br /></span><span style="color: #0000BB">$input </span><span style="color: #007700">= <<<'EOF'<br /></span><span style="color: #DD0000">1;PHP;Likes dollar signs<br />2;Python;Likes whitespace<br />3;Ruby;Likes blocks<br /></span><span style="color: #007700">EOF;<br /><br />function </span><span style="color: #0000BB">input_parser</span><span style="color: #007700">(</span><span style="color: #0000BB">$input</span><span style="color: #007700">) {<br /> foreach (</span><span style="color: #0000BB">explode</span><span style="color: #007700">(</span><span style="color: #DD0000">"\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">$input</span><span style="color: #007700">) as </span><span style="color: #0000BB">$line</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">$fields </span><span style="color: #007700">= </span><span style="color: #0000BB">explode</span><span style="color: #007700">(</span><span style="color: #DD0000">';'</span><span style="color: #007700">, </span><span style="color: #0000BB">$line</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">$id </span><span style="color: #007700">= </span><span style="color: #0000BB">array_shift</span><span style="color: #007700">(</span><span style="color: #0000BB">$fields</span><span style="color: #007700">);<br /><br /> </span><span style="color: #0000BB">yield $id </span><span style="color: #007700">=> </span><span style="color: #0000BB">$fields</span><span style="color: #007700">;<br /> }<br />}<br /><br />foreach (</span><span style="color: #0000BB">input_parser</span><span style="color: #007700">(</span><span style="color: #0000BB">$input</span><span style="color: #007700">) as </span><span style="color: #0000BB">$id </span><span style="color: #007700">=> </span><span style="color: #0000BB">$fields</span><span style="color: #007700">) {<br /> echo </span><span style="color: #DD0000">"</span><span style="color: #0000BB">$id</span><span style="color: #DD0000">:\n"</span><span style="color: #007700">;<br /> echo </span><span style="color: #DD0000">" </span><span style="color: #0000BB">$fields</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">]</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br /> echo </span><span style="color: #DD0000">" </span><span style="color: #0000BB">$fields</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">]</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
1:
PHP
Likes dollar signs
2:
Python
Likes whitespace
3:
Ruby
Likes blocks
</pre></div>
</div>
</div>
<div class="caution"><strong class="caution">Caution</strong>
<p class="para">
As with the simple value yields shown earlier, yielding a key/value pair
in an expression context requires the yield statement to be
parenthesised:
</p>
<div class="informalexample">
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
$data = (yield $key => $value);</span>
</code></div>
</div>
</div>
</div>
</div>
<div class="sect3" id="control-structures.yield.null">
<h4 class="title">Yielding null values</h4>
<p class="para">
Yield can be called without an argument to yield a <strong><code>NULL</code></strong> value with an
automatic key.
</p>
<div class="example" id="example-277">
<p><strong>Example #3 Yielding <strong><code>NULL</code></strong>s</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">gen_three_nulls</span><span style="color: #007700">() {<br /> foreach (</span><span style="color: #0000BB">range</span><span style="color: #007700">(</span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #0000BB">3</span><span style="color: #007700">) as </span><span style="color: #0000BB">$i</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">yield</span><span style="color: #007700">;<br /> }<br />}<br /><br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">iterator_to_array</span><span style="color: #007700">(</span><span style="color: #0000BB">gen_three_nulls</span><span style="color: #007700">()));<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
array(3) {
[0]=>
NULL
[1]=>
NULL
[2]=>
NULL
}
</pre></div>
</div>
</div>
</div>
<div class="sect3" id="control-structures.yield.references">
<h4 class="title">Yielding by reference</h4>
<p class="para">
Generator functions are able to yield values by reference as well as by
value. This is done in the same way as
<a href="functions.returning-values.html" class="link">returning references from functions</a>:
by prepending an ampersand to the function name.
</p>
<div class="example" id="example-278">
<p><strong>Example #4 Yielding values by reference</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">function &</span><span style="color: #0000BB">gen_reference</span><span style="color: #007700">() {<br /> </span><span style="color: #0000BB">$value </span><span style="color: #007700">= </span><span style="color: #0000BB">3</span><span style="color: #007700">;<br /><br /> while (</span><span style="color: #0000BB">$value </span><span style="color: #007700">> </span><span style="color: #0000BB">0</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">yield $value</span><span style="color: #007700">;<br /> }<br />}<br /><br /></span><span style="color: #FF8000">/*<br /> * Note that we can change $number within the loop, and<br /> * because the generator is yielding references, $value<br /> * within gen_reference() changes.<br /> */<br /></span><span style="color: #007700">foreach (</span><span style="color: #0000BB">gen_reference</span><span style="color: #007700">() as &</span><span style="color: #0000BB">$number</span><span style="color: #007700">) {<br /> echo (--</span><span style="color: #0000BB">$number</span><span style="color: #007700">).</span><span style="color: #DD0000">'... '</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
2... 1... 0...
</pre></div>
</div>
</div>
</div>
</div>
<div class="sect2" id="language.generators.object">
<h3 class="title"><a href="class.generator.html" class="classname">Generator</a> objects</h3>
<p class="para">
When a generator function is called for the first time, an object of the
internal <a href="class.generator.html" class="classname">Generator</a> class is returned. This object
implements the <a href="class.iterator.html" class="classname">Iterator</a> interface in much the same
way as a forward-only iterator object would.
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="language.generators.overview.html">Generators overview</a></div>
<div class="next" style="text-align: right; float: right;"><a href="language.generators.comparison.html">Comparing generators with Iterator objects</a></div>
<div class="up"><a href="language.generators.html">Generators</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
