<!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>Iterables</title> </head> <body><div class="manualnavbar" style="text-align: center;"> <div class="prev" style="text-align: left; float: left;"><a href="language.types.array.html">Arrays</a></div> <div class="next" style="text-align: right; float: right;"><a href="language.types.object.html">Objects</a></div> <div class="up"><a href="language.types.html">Types</a></div> <div class="home"><a href="index.html">PHP Manual</a></div> </div><hr /><div id="language.types.iterable" class="sect1"> <h2 class="title">Iterables</h2> <p class="para"> <span class="type"><span class="type Iterable">Iterable</span></span> is a pseudo-type introduced in PHP 7.1. It accepts any <span class="type"><a href="language.types.array.html" class="type array">array</a></span> or object implementing the <a href="class.traversable.html" class="classname">Traversable</a> interface. Both of these types are iterable using <a href="control-structures.foreach.html" class="link">foreach</a> and can be used with <strong class="command">yield from</strong> within a <a href="language.generators.html" class="link">generator</a>. </p> <div class="sect2" id="language.types.iterable.using"> <h3 class="title">Using Iterables</h3> <p class="para"> Iterable can be used as a parameter type to indicate that a function requires a set of values, but does not care about the form of the value set since it will be used with <a href="control-structures.foreach.html" class="link">foreach</a>. If a value is not an array or instance of <a href="class.traversable.html" class="classname">Traversable</a>, a <a href="class.typeerror.html" class="classname">TypeError</a> will be thrown. </p> <p class="para"> <div class="example" id="example-70"> <p><strong>Example #1 Iterable parameter type example </strong></p> <div class="example-contents"> <div class="phpcode"><code><span style="color: #000000"> <span style="color: #0000BB"><?php<br /><br /></span><span style="color: #007700">function </span><span style="color: #0000BB">foo</span><span style="color: #007700">(</span><span style="color: #0000BB">iterable $iterable</span><span style="color: #007700">) {<br /> foreach (</span><span style="color: #0000BB">$iterable </span><span style="color: #007700">as </span><span style="color: #0000BB">$value</span><span style="color: #007700">) {<br /> </span><span style="color: #FF8000">// ...<br /> </span><span style="color: #007700">} <br />}<br /><br /></span><span style="color: #0000BB">?></span> </span> </code></div> </div> </div> </p> <p class="para"> Parameters declared as iterable may use <strong><code>NULL</code></strong> or an array as a default value. </p> <p class="para"> <div class="example" id="example-71"> <p><strong>Example #2 Iterable parameter default value example </strong></p> <div class="example-contents"> <div class="phpcode"><code><span style="color: #000000"> <span style="color: #0000BB"><?php<br /><br /></span><span style="color: #007700">function </span><span style="color: #0000BB">foo</span><span style="color: #007700">(</span><span style="color: #0000BB">iterable $iterable </span><span style="color: #007700">= []) {<br /> </span><span style="color: #FF8000">// ...<br /></span><span style="color: #007700">}<br /><br /></span><span style="color: #0000BB">?></span> </span> </code></div> </div> </div> </p> <p class="para"> Iterable can also be used as a return type to indicate a function will return an iterable value. If the returned value is not an array or instance of <a href="class.traversable.html" class="classname">Traversable</a>, a <a href="class.typeerror.html" class="classname">TypeError</a> will be thrown. </p> <p class="para"> <div class="example" id="example-72"> <p><strong>Example #3 Iterable return type example </strong></p> <div class="example-contents"> <div class="phpcode"><code><span style="color: #000000"> <span style="color: #0000BB"><?php<br /><br /></span><span style="color: #007700">function </span><span style="color: #0000BB">bar</span><span style="color: #007700">(): </span><span style="color: #0000BB">iterable </span><span style="color: #007700">{<br /> return [</span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #0000BB">2</span><span style="color: #007700">, </span><span style="color: #0000BB">3</span><span style="color: #007700">];<br />}<br /><br /></span><span style="color: #0000BB">?></span> </span> </code></div> </div> </div> </p> <p class="para"> Functions declaring iterable as a return type may also be <a href="language.generators.html" class="link">generators</a>. </p> <p class="para"> <div class="example" id="example-73"> <p><strong>Example #4 Iterable generator return type example </strong></p> <div class="example-contents"> <div class="phpcode"><code><span style="color: #000000"> <span style="color: #0000BB"><?php<br /><br /></span><span style="color: #007700">function </span><span style="color: #0000BB">gen</span><span style="color: #007700">(): </span><span style="color: #0000BB">iterable </span><span style="color: #007700">{<br /> </span><span style="color: #0000BB">yield 1</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">yield 2</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">yield 3</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #0000BB">?></span> </span> </code></div> </div> </div> </p> </div> <div class="sect2" id="language.types.iterable.variance"> <h3 class="title">Iterable Type Variance</h3> <p class="para"> Classes extending/implementing may broaden methods using <span class="type"><a href="language.types.array.html" class="type array">array</a></span> or <a href="class.traversable.html" class="classname">Traversable</a> as parameter types to <span class="type"><span class="type iterable">iterable</span></span> or narrow return types from <span class="type"><span class="type iterable">iterable</span></span> to <span class="type"><a href="language.types.array.html" class="type array">array</a></span> or <a href="class.traversable.html" class="classname">Traversable</a>. </p> <p class="para"> <div class="example" id="example-74"> <p><strong>Example #5 Iterable type variance example </strong></p> <div class="example-contents"> <div class="phpcode"><code><span style="color: #000000"> <span style="color: #0000BB"><?php<br /><br /></span><span style="color: #007700">interface </span><span style="color: #0000BB">Example </span><span style="color: #007700">{<br /> public function </span><span style="color: #0000BB">method</span><span style="color: #007700">(array </span><span style="color: #0000BB">$array</span><span style="color: #007700">): </span><span style="color: #0000BB">iterable</span><span style="color: #007700">;<br />}<br /><br />class </span><span style="color: #0000BB">ExampleImplementation </span><span style="color: #007700">implements </span><span style="color: #0000BB">Example </span><span style="color: #007700">{<br /> public function </span><span style="color: #0000BB">method</span><span style="color: #007700">(</span><span style="color: #0000BB">iterable $iterable</span><span style="color: #007700">): array {<br /> </span><span style="color: #FF8000">// Parameter broadened and return type narrowed.<br /> </span><span style="color: #007700">}<br />}<br /><br /></span><span style="color: #0000BB">?></span> </span> </code></div> </div> </div> </p> </div> </div><hr /><div class="manualnavbar" style="text-align: center;"> <div class="prev" style="text-align: left; float: left;"><a href="language.types.array.html">Arrays</a></div> <div class="next" style="text-align: right; float: right;"><a href="language.types.object.html">Objects</a></div> <div class="up"><a href="language.types.html">Types</a></div> <div class="home"><a href="index.html">PHP Manual</a></div> </div></body></html>