Iterating Objects with foreach (Iterator & IteratorAggregate)

Also Known As

TL;DR

Explanation

When you write foreach ($obj as $key => $value) on an object, PHP picks one of three strategies. If the class implements Iterator, PHP calls its five methods in order: rewind(), then a loop of valid(), current(), key(), next(). If the class implements IteratorAggregate, PHP calls getIterator(), which must return a Traversable (often an inner ArrayIterator or a generator). If the class implements neither, foreach falls back to iterating the object's public properties in declaration order — useful for plain DTOs but a leaky abstraction for encapsulated classes.

Iterator gives you full manual control: you decide what 'current' means, how keys advance, and when iteration ends. This is ideal for streaming data, lazy database cursors, or computed sequences where you do not want to materialise everything into an array. The downside is boilerplate — five methods to maintain a cursor position correctly, including the easy-to-forget rewind() that must reset state so the same object can be looped twice.

IteratorAggregate is almost always the better choice for collection classes. You implement a single getIterator() method and delegate to a generator or ArrayIterator, getting correct iteration semantics for free. Since PHP 5.5, returning a generator from getIterator() is the cleanest pattern: yield each element and PHP handles the cursor mechanics.

A common subtlety: iterating an Iterator object inside nested foreach loops over the same instance shares cursor state and breaks, because there is one internal pointer. Generators and IteratorAggregate returning fresh iterators avoid this. Also note that foreach over an object's properties only sees properties visible from the calling scope, so private properties are hidden when iterating from outside the class. Prefer explicit Traversable implementations over relying on property iteration for anything beyond trivial value objects.

Common Misconception

Why It Matters

Common Mistakes

• Forgetting to reset state in rewind(), so the object cannot be iterated a second time.
• Implementing Iterator with hand-rolled cursor methods when IteratorAggregate returning a generator would be simpler and correct.
• Reusing a single Iterator instance in nested foreach loops, where the shared internal pointer corrupts iteration.
• Relying on foreach iterating public properties as a public API, which breaks encapsulation and changes with property visibility.
• Returning a non-Traversable value from getIterator(), which triggers an exception at iteration time.

Code Examples

// Hand-rolled Iterator with a forgotten rewind reset
class UserCollection implements Iterator {
    private array $users;
    private int $pos = 0;

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

    public function current(): mixed { return $this->users[$this->pos]; }
    public function key(): mixed { return $this->pos; }
    public function next(): void { $this->pos++; }
    public function valid(): bool { return isset($this->users[$this->pos]); }
    // rewind does nothing — second foreach yields nothing
    public function rewind(): void {}
}

$c = new UserCollection(['a', 'b']);
foreach ($c as $u) { /* works once */ }
foreach ($c as $u) { /* broken: pos never reset */ }

// IteratorAggregate delegating to a generator — concise and correct
class UserCollection implements IteratorAggregate {
    public function __construct(private array $users) {}

    public function getIterator(): Traversable {
        foreach ($this->users as $key => $user) {
            yield $key => $user;
        }
    }
}

$c = new UserCollection(['a', 'b']);
foreach ($c as $u) { /* works */ }
foreach ($c as $u) { /* works again: fresh generator each time */ }

Tags

🧠 Logic Engine

References

• https://www.php.net/manual/en/class.iterator.php
• https://www.php.net/manual/en/class.iteratoraggregate.php
• https://www.php.net/manual/en/language.oop5.iterations.php