Editing Iterator (section)

=== PHP ===
[[File:UML PHP iterator interface.svg|right|UML class diagram of the Iterator interface in PHP]]
[[PHP]]'s [[foreach loop|<code>foreach</code> loop]] was introduced in version 4.0 and made compatible with objects as values in 4.0 Beta 4.<ref>{{cite web
| url        = https://secure.php.net/ChangeLog-4.php#4.0b4
| title      = PHP 4 ChangeLog
| access-date = 2015-10-13
| date       = 2000-02-20
| publisher  = The PHP Group
}}</ref> However, support for iterators was added in PHP&nbsp;5 through the introduction of the internal<ref>Internal refers to the fact that the interface cannot be implemented in PHP scripts, only in the [[C (programming language)]] source.</ref> <code>Traversable</code> interface.<ref>{{cite web
| url        = https://secure.php.net/class.traversable
| title      = The Traversable interface
| access-date = 2015-10-13
| publisher  = The PHP Group
}}</ref> The two main interfaces for implementation in PHP scripts that enable objects to be iterated via the <code>foreach</code> loop are <code>Iterator</code> and <code>IteratorAggregate</code>. The latter does not require the implementing class to declare all required methods, instead it implements an [[Mutator method|accessor]] method (<code>getIterator</code>) that returns an instance of <code>Traversable</code>. The [[Standard PHP Library]] provides several classes to work with special iterators.<ref>{{cite web
| url        = https://secure.php.net/spl.iterators
| title      = Iterators
| access-date = 2015-10-13
| publisher  = The PHP Group
}}</ref> PHP also supports [[Generator (computer programming)|Generators]] since 5.5.<ref>{{cite web
| url        = https://secure.php.net/ChangeLog-5.php#5.5.0
| title      = PHP 5 ChangeLog
| access-date = 2015-10-13
| date       = 2013-06-20
| publisher  = The PHP Group
}}</ref>

The simplest implementation is by wrapping an array, this can be useful for [[PHP#TYPE-HINTING|type hinting]] and [[information hiding]].

<syntaxhighlight lang="php">
namespace Wikipedia\Iterator;

final class ArrayIterator extends \Iterator
{
    private array $array;

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

    public function rewind(): void
    {
        echo 'rewinding' , PHP_EOL;
        reset($this->array);
    }

    public function current()
    {
        $value = current($this->array);
        echo "current: {$value}", PHP_EOL;
        return $value;
    }

    public function key()
    {
        $key = key($this->array);
        echo "key: {$key}", PHP_EOL;
        return $key;
    }

    public function next()
    {
        $value = next($this->array);
        echo "next: {$value}", PHP_EOL;
        return $value;
    }

    public function valid(): bool
    {
        $valid = $this->current() !== false;
        echo 'valid: ', ($valid ? 'true' : 'false'), PHP_EOL;
        return $valid;
    }
}
</syntaxhighlight>

All methods of the example class are used during the execution of a complete foreach loop (<code>foreach ($iterator as $key => $current) {}</code>). The iterator's methods are executed in the following order:
# <code>$iterator->rewind()</code> ensures that the internal structure starts from the beginning.
# <code>$iterator->valid()</code> returns ''true'' in this example.
# <code>$iterator->current()</code> returned value is stored in <code>$value</code>.
# <code>$iterator->key()</code> returned value is stored in <code>$key</code>.
# <code>$iterator->next()</code> advances to the next element in the internal structure.
# <code>$iterator->valid()</code> returns ''false'' and the loop is aborted.

The next example illustrates a PHP class that implements the <code>Traversable</code> interface, which could be wrapped in an <code>IteratorIterator</code> class to act upon the data before it is returned to the <code>foreach</code> loop. The usage together with the <code>MYSQLI_USE_RESULT</code> constant allows PHP scripts to iterate result sets with billions of rows with very little memory usage. These features are not exclusive to PHP nor to its MySQL class implementations (e.g. the <code>PDOStatement</code> class implements the <code>Traversable</code> interface as well).

<syntaxhighlight lang="php">
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new \mysqli('host.example.com', 'username', 'password', 'database_name');

// The \mysqli_result class that is returned by the method call implements the internal Traversable interface.
foreach ($mysqli->query('SELECT `a`, `b`, `c` FROM `table`', MYSQLI_USE_RESULT) as $row) {
    // Act on the returned row, which is an associative array.
}
</syntaxhighlight>