Iterators & IteratorAggregate

Also Known As

TL;DR

Explanation

PHP's Iterator interface requires five methods: current(), key(), next(), rewind(), valid(). IteratorAggregate requires just getIterator(), which returns an Iterator or Traversable — simpler for delegation. Custom iterators enable foreach over database result sets (fetching row by row), API paginated responses, filesystem trees, and infinite sequences — all with O(1) memory. PHP's SPL provides useful built-in iterators: DirectoryIterator, FilesystemIterator, RecursiveIteratorIterator, ArrayIterator, and LimitIterator. Generators (yield) are often a simpler alternative to manual Iterator implementation.

Common Misconception

Why It Matters

Common Mistakes

• Implementing Iterator but forgetting rewind() — the iterator works once then is silently exhausted.
• Not implementing IteratorAggregate when you just need to wrap an existing array or Traversable — it's simpler.
• Returning false from current() on an empty iterator instead of returning null — both work but false is less predictable.
• Not using generators (yield) for lazy sequences — they automatically implement the Iterator protocol.

Code Examples

// Broken Iterator — missing rewind:
class NumberRange implements Iterator {
    private int $current = 0;
    public function __construct(private int $start, private int $end) {
        $this->current = $start;
    }
    public function current(): int { return $this->current; }
    public function key(): int { return $this->current - $this->start; }
    public function next(): void { $this->current++; }
    public function valid(): bool { return $this->current <= $this->end; }
    // Missing: public function rewind(): void { $this->current = $this->start; }
}

// Implement Iterator to make a class foreach-able
class NumberRange implements Iterator {
    private int \$current;
    public function __construct(private int \$start, private int \$end) {
        \$this->current = \$start;
    }
    public function current(): int { return \$this->current; }
    public function key(): int     { return \$this->current - \$this->start; }
    public function next(): void   { \$this->current++; }
    public function rewind(): void { \$this->current = \$this->start; }
    public function valid(): bool  { return \$this->current <= \$this->end; }
}

foreach (new NumberRange(1, 3) as \$i) { echo \$i; } // 1 2 3

// IteratorAggregate — simpler approach
class UserCollection implements IteratorAggregate {
    public function getIterator(): ArrayIterator {
        return new ArrayIterator(\$this->users);
    }
}

References

• ↗ https://www.php.net/manual/en/class.iterator.php
• ↗ https://www.php.net/manual/en/class.iteratoraggregate.php

Tags

Related Terms