<!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>Object Iteration</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="language.oop5.overloading.html">Overloading</a></div>
<div class="next" style="text-align: right; float: right;"><a href="language.oop5.magic.html">Magic Methods</a></div>
<div class="up"><a href="language.oop5.html">Classes and Objects</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="language.oop5.iterations" class="sect1">
<h2 class="title">Object Iteration</h2>
<p class="para">
PHP 5 provides a way for objects to be defined so it is possible to iterate
through a list of items, with, for example a <a href="control-structures.foreach.html" class="link">foreach</a> statement. By default,
all <a href="language.oop5.visibility.html" class="link">visible</a> properties will be used
for the iteration.
</p>
<div class="example" id="example-216">
<p><strong>Example #1 Simple Object Iteration</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">class </span><span style="color: #0000BB">MyClass<br /></span><span style="color: #007700">{<br /> public </span><span style="color: #0000BB">$var1 </span><span style="color: #007700">= </span><span style="color: #DD0000">'value 1'</span><span style="color: #007700">;<br /> public </span><span style="color: #0000BB">$var2 </span><span style="color: #007700">= </span><span style="color: #DD0000">'value 2'</span><span style="color: #007700">;<br /> public </span><span style="color: #0000BB">$var3 </span><span style="color: #007700">= </span><span style="color: #DD0000">'value 3'</span><span style="color: #007700">;<br /><br /> protected </span><span style="color: #0000BB">$protected </span><span style="color: #007700">= </span><span style="color: #DD0000">'protected var'</span><span style="color: #007700">;<br /> private </span><span style="color: #0000BB">$private </span><span style="color: #007700">= </span><span style="color: #DD0000">'private var'</span><span style="color: #007700">;<br /><br /> function </span><span style="color: #0000BB">iterateVisible</span><span style="color: #007700">() {<br /> echo </span><span style="color: #DD0000">"MyClass::iterateVisible:\n"</span><span style="color: #007700">;<br /> foreach(</span><span style="color: #0000BB">$this </span><span style="color: #007700">as </span><span style="color: #0000BB">$key </span><span style="color: #007700">=> </span><span style="color: #0000BB">$value</span><span style="color: #007700">) {<br /> print </span><span style="color: #DD0000">"</span><span style="color: #0000BB">$key</span><span style="color: #DD0000"> => </span><span style="color: #0000BB">$value</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br /> }<br /> }<br />}<br /><br /></span><span style="color: #0000BB">$class </span><span style="color: #007700">= new </span><span style="color: #0000BB">MyClass</span><span style="color: #007700">();<br /><br />foreach(</span><span style="color: #0000BB">$class </span><span style="color: #007700">as </span><span style="color: #0000BB">$key </span><span style="color: #007700">=> </span><span style="color: #0000BB">$value</span><span style="color: #007700">) {<br /> print </span><span style="color: #DD0000">"</span><span style="color: #0000BB">$key</span><span style="color: #DD0000"> => </span><span style="color: #0000BB">$value</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br />}<br />echo </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br /><br /><br /></span><span style="color: #0000BB">$class</span><span style="color: #007700">-></span><span style="color: #0000BB">iterateVisible</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>
var1 => value 1
var2 => value 2
var3 => value 3
MyClass::iterateVisible:
var1 => value 1
var2 => value 2
var3 => value 3
protected => protected var
private => private var
</pre></div>
</div>
</div>
<p class="para">
As the output shows, the <a href="control-structures.foreach.html" class="link">foreach</a> iterated through all of the
<a href="language.oop5.visibility.html" class="link">visible</a> properties that could be
accessed.
</p>
<p class="para">
To take it a step further, the <span class="interfacename"><a href="class.iterator.html" class="interfacename">Iterator</a></span>
<a href="language.oop5.interfaces.html" class="link">interface</a> may be implemented.
This allows the object to dictate how it will be iterated and what values will
be available on each iteration.
</p>
<div class="example" id="example-217">
<p><strong>Example #2 Object Iteration implementing Iterator</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">class </span><span style="color: #0000BB">MyIterator </span><span style="color: #007700">implements </span><span style="color: #0000BB">Iterator<br /></span><span style="color: #007700">{<br /> private </span><span style="color: #0000BB">$var </span><span style="color: #007700">= array();<br /><br /> public function </span><span style="color: #0000BB">__construct</span><span style="color: #007700">(</span><span style="color: #0000BB">$array</span><span style="color: #007700">)<br /> {<br /> if (</span><span style="color: #0000BB">is_array</span><span style="color: #007700">(</span><span style="color: #0000BB">$array</span><span style="color: #007700">)) {<br /> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">var </span><span style="color: #007700">= </span><span style="color: #0000BB">$array</span><span style="color: #007700">;<br /> }<br /> }<br /><br /> public function </span><span style="color: #0000BB">rewind</span><span style="color: #007700">()<br /> {<br /> echo </span><span style="color: #DD0000">"rewinding\n"</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">reset</span><span style="color: #007700">(</span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">var</span><span style="color: #007700">);<br /> }<br /> <br /> public function </span><span style="color: #0000BB">current</span><span style="color: #007700">()<br /> {<br /> </span><span style="color: #0000BB">$var </span><span style="color: #007700">= </span><span style="color: #0000BB">current</span><span style="color: #007700">(</span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">var</span><span style="color: #007700">);<br /> echo </span><span style="color: #DD0000">"current: </span><span style="color: #0000BB">$var</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br /> return </span><span style="color: #0000BB">$var</span><span style="color: #007700">;<br /> }<br /> <br /> public function </span><span style="color: #0000BB">key</span><span style="color: #007700">() <br /> {<br /> </span><span style="color: #0000BB">$var </span><span style="color: #007700">= </span><span style="color: #0000BB">key</span><span style="color: #007700">(</span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">var</span><span style="color: #007700">);<br /> echo </span><span style="color: #DD0000">"key: </span><span style="color: #0000BB">$var</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br /> return </span><span style="color: #0000BB">$var</span><span style="color: #007700">;<br /> }<br /> <br /> public function </span><span style="color: #0000BB">next</span><span style="color: #007700">() <br /> {<br /> </span><span style="color: #0000BB">$var </span><span style="color: #007700">= </span><span style="color: #0000BB">next</span><span style="color: #007700">(</span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">var</span><span style="color: #007700">);<br /> echo </span><span style="color: #DD0000">"next: </span><span style="color: #0000BB">$var</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br /> return </span><span style="color: #0000BB">$var</span><span style="color: #007700">;<br /> }<br /> <br /> public function </span><span style="color: #0000BB">valid</span><span style="color: #007700">()<br /> {<br /> </span><span style="color: #0000BB">$key </span><span style="color: #007700">= </span><span style="color: #0000BB">key</span><span style="color: #007700">(</span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">var</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">$var </span><span style="color: #007700">= (</span><span style="color: #0000BB">$key </span><span style="color: #007700">!== </span><span style="color: #0000BB">NULL </span><span style="color: #007700">&& </span><span style="color: #0000BB">$key </span><span style="color: #007700">!== </span><span style="color: #0000BB">FALSE</span><span style="color: #007700">);<br /> echo </span><span style="color: #DD0000">"valid: </span><span style="color: #0000BB">$var</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br /> return </span><span style="color: #0000BB">$var</span><span style="color: #007700">;<br /> }<br /><br />}<br /><br /></span><span style="color: #0000BB">$values </span><span style="color: #007700">= array(</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 /></span><span style="color: #0000BB">$it </span><span style="color: #007700">= new </span><span style="color: #0000BB">MyIterator</span><span style="color: #007700">(</span><span style="color: #0000BB">$values</span><span style="color: #007700">);<br /><br />foreach (</span><span style="color: #0000BB">$it </span><span style="color: #007700">as </span><span style="color: #0000BB">$a </span><span style="color: #007700">=> </span><span style="color: #0000BB">$b</span><span style="color: #007700">) {<br /> print </span><span style="color: #DD0000">"</span><span style="color: #0000BB">$a</span><span style="color: #DD0000">: </span><span style="color: #0000BB">$b</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>
rewinding
valid: 1
current: 1
key: 0
0: 1
next: 2
valid: 1
current: 2
key: 1
1: 2
next: 3
valid: 1
current: 3
key: 2
2: 3
next:
valid:
</pre></div>
</div>
</div>
<p class="para">
The <span class="interfacename"><a href="class.iteratoraggregate.html" class="interfacename">IteratorAggregate</a></span>
<a href="language.oop5.interfaces.html" class="link">interface</a>
can be used as an alternative to implementing all of the
<span class="interfacename"><a href="class.iterator.html" class="interfacename">Iterator</a></span> methods.
<span class="interfacename"><a href="class.iteratoraggregate.html" class="interfacename">IteratorAggregate</a></span> only requires the
implementation of a single method,
<span class="methodname"><a href="iteratoraggregate.getiterator.html" class="methodname">IteratorAggregate::getIterator()</a></span>, which should return
an instance of a class implementing <span class="interfacename"><a href="class.iterator.html" class="interfacename">Iterator</a></span>.
</p>
<div class="example" id="example-218">
<p><strong>Example #3 Object Iteration implementing IteratorAggregate</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">class </span><span style="color: #0000BB">MyCollection </span><span style="color: #007700">implements </span><span style="color: #0000BB">IteratorAggregate<br /></span><span style="color: #007700">{<br /> private </span><span style="color: #0000BB">$items </span><span style="color: #007700">= array();<br /> private </span><span style="color: #0000BB">$count </span><span style="color: #007700">= </span><span style="color: #0000BB">0</span><span style="color: #007700">;<br /><br /> </span><span style="color: #FF8000">// Required definition of interface IteratorAggregate<br /> </span><span style="color: #007700">public function </span><span style="color: #0000BB">getIterator</span><span style="color: #007700">() {<br /> return new </span><span style="color: #0000BB">MyIterator</span><span style="color: #007700">(</span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">items</span><span style="color: #007700">);<br /> }<br /><br /> public function </span><span style="color: #0000BB">add</span><span style="color: #007700">(</span><span style="color: #0000BB">$value</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">items</span><span style="color: #007700">[</span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">count</span><span style="color: #007700">++] = </span><span style="color: #0000BB">$value</span><span style="color: #007700">;<br /> }<br />}<br /><br /></span><span style="color: #0000BB">$coll </span><span style="color: #007700">= new </span><span style="color: #0000BB">MyCollection</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">$coll</span><span style="color: #007700">-></span><span style="color: #0000BB">add</span><span style="color: #007700">(</span><span style="color: #DD0000">'value 1'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$coll</span><span style="color: #007700">-></span><span style="color: #0000BB">add</span><span style="color: #007700">(</span><span style="color: #DD0000">'value 2'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$coll</span><span style="color: #007700">-></span><span style="color: #0000BB">add</span><span style="color: #007700">(</span><span style="color: #DD0000">'value 3'</span><span style="color: #007700">);<br /><br />foreach (</span><span style="color: #0000BB">$coll </span><span style="color: #007700">as </span><span style="color: #0000BB">$key </span><span style="color: #007700">=> </span><span style="color: #0000BB">$val</span><span style="color: #007700">) {<br /> echo </span><span style="color: #DD0000">"key/value: [</span><span style="color: #0000BB">$key</span><span style="color: #DD0000"> -> </span><span style="color: #0000BB">$val</span><span style="color: #DD0000">]\n\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>
rewinding
current: value 1
valid: 1
current: value 1
key: 0
key/value: [0 -> value 1]
next: value 2
current: value 2
valid: 1
current: value 2
key: 1
key/value: [1 -> value 2]
next: value 3
current: value 3
valid: 1
current: value 3
key: 2
key/value: [2 -> value 3]
next:
current:
valid:
</pre></div>
</div>
</div>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
For more examples of iterators, see the
<a href="spl.iterators.html" class="link">SPL Extension</a>.
</p>
</p></blockquote>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
Users of PHP 5.5 and later may also want to investigate
<a href="language.generators.html" class="link">generators</a>, which provide an
alternative way of defining iterators.
</p>
</p></blockquote>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="language.oop5.overloading.html">Overloading</a></div>
<div class="next" style="text-align: right; float: right;"><a href="language.oop5.magic.html">Magic Methods</a></div>
<div class="up"><a href="language.oop5.html">Classes and Objects</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
