<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 328430 $ -->
 <sect1 xml:id="language.oop5.iterations" xmlns="http://docbook.org/ns/docbook">
  <title>Object Iteration</title>
  <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 &foreach; statement. By default,
   all <link linkend="language.oop5.visibility">visible</link> properties will be used
   for the iteration.

  </para>

  <example>
   <title>Simple Object Iteration</title>
   <programlisting role="php">
<![CDATA[
<?php
class MyClass
{
    public $var1 = 'value 1';
    public $var2 = 'value 2';
    public $var3 = 'value 3';

    protected $protected = 'protected var';
    private   $private   = 'private var';

    function iterateVisible() {
       echo "MyClass::iterateVisible:\n";
       foreach($this as $key => $value) {
           print "$key => $value\n";
       }
    }
}

$class = new MyClass();

foreach($class as $key => $value) {
    print "$key => $value\n";
}
echo "\n";


$class->iterateVisible();

?>
]]>
   </programlisting>
   &example.outputs; 
   <screen role="php">
<![CDATA[
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
]]>
   </screen>

  </example>

 <para>
  As the output shows, the &foreach; iterated through all of the
  <link linkend="language.oop5.visibility">visible</link> properties that could be
  accessed.
 </para>
 <para>
  To take it a step further, the <interfacename>Iterator</interfacename>
  <link linkend="language.oop5.interfaces">interface</link> may be implemented.
  This allows the object to dictate how it will be iterated and what values will
  be available on each iteration.
 </para>

  <example>
   <title>Object Iteration implementing Iterator</title>
   <programlisting role="php">
<![CDATA[
<?php
class MyIterator implements Iterator
{
    private $var = array();

    public function __construct($array)
    {
        if (is_array($array)) {
            $this->var = $array;
        }
    }

    public function rewind()
    {
        echo "rewinding\n";
        reset($this->var);
    }
  
    public function current()
    {
        $var = current($this->var);
        echo "current: $var\n";
        return $var;
    }
  
    public function key() 
    {
        $var = key($this->var);
        echo "key: $var\n";
        return $var;
    }
  
    public function next() 
    {
        $var = next($this->var);
        echo "next: $var\n";
        return $var;
    }
  
    public function valid()
    {
        $key = key($this->var);
        $var = ($key !== NULL && $key !== FALSE);
        echo "valid: $var\n";
        return $var;
    }

}

$values = array(1,2,3);
$it = new MyIterator($values);

foreach ($it as $a => $b) {
    print "$a: $b\n";
}
?>
]]>
   </programlisting>
   &example.outputs;
   <screen role="php">
<![CDATA[
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: 
]]>
   </screen>

  </example>

  <para>
   The <interfacename>IteratorAggregate</interfacename>
   <link linkend="language.oop5.interfaces">interface</link>
   can be used as an alternative to implementing all of the
   <interfacename>Iterator</interfacename> methods.
   <interfacename>IteratorAggregate</interfacename> only requires the
   implementation of a single method,
   <methodname>IteratorAggregate::getIterator</methodname>, which should return
   an instance of a class implementing <interfacename>Iterator</interfacename>.
  </para>

  <example>
   <title>Object Iteration implementing IteratorAggregate</title>
   <programlisting role="php">
<![CDATA[
<?php
class MyCollection implements IteratorAggregate
{
    private $items = array();
    private $count = 0;

    // Required definition of interface IteratorAggregate
    public function getIterator() {
        return new MyIterator($this->items);
    }

    public function add($value) {
        $this->items[$this->count++] = $value;
    }
}

$coll = new MyCollection();
$coll->add('value 1');
$coll->add('value 2');
$coll->add('value 3');

foreach ($coll as $key => $val) {
    echo "key/value: [$key -> $val]\n\n";
}
?>
]]>
   </programlisting>
   &example.outputs;  
   <screen role="php">
<![CDATA[
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:
]]>
   </screen>

  </example>

  <note>
   <para>
    For more examples of iterators, see the
    <link linkend="spl.iterators">SPL Extension</link>.
   </para>
  </note> 

  <note>
   <para>
    Users of PHP 5.5 and later may also want to investigate
    <link linkend="language.generators">generators</link>, which provide an
    alternative way of defining iterators.
   </para>
  </note> 

 </sect1>
 
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->