Implementing `Iterator` and `IteratorAggregate` for Custom Object Iteration

To make PHP custom objects iterable, you can choose IteratorAggregate or Iterator interface; 1. When using IteratorAggregate, you only need to implement the getIterator() method and return a Traversable object, which is suitable for simply wrapping existing collections; 2. When using Iterator, you need to implement five methods: rewind, current, key, next and valid, which are suitable for scenarios where it requires fine control of the iteration process; you should choose the appropriate method based on whether complex iteration logic is needed, both of which ensure that the object can be used in foreach.

When working with custom objects in PHP, you may want to make them iterable—so they can be used in foreach loops just like arrays or other built-in iterable types. PHP provides two primary interfaces for this: Iterator and IteratorAggregate . Each offer a different level of control and simplicity depending on your use case.

Let's explore both approaches and how to implement them effectively.

Using IteratorAggregate (Simpler Approach)

The IteratorAggregate interface is ideal when you want to wrap an existing iterable (like an array or ArrayObject ) and expose it for iteration without managing internal state manually.

You only need to implement one method: getIterator() , which returns an Traversable object.

 class BookCollection implements IteratorAggregate
{
    private array $books;

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

    public function getIterator(): Traversable
    {
        return new ArrayIterator($this->books);
    }
}

Now you can iterate over the object:

 $collection = new BookCollection(['PHP Basics', 'Design Patterns', 'Advanced OOP']);

foreach ($collection as $book) {
    echo $book . PHP_EOL;
}

This outputs:

 PHP Basics
Design Patterns
Advanced OOP

✅ Pros :

• Simple to implement
• Reuses existing iterators like ArrayIterator
• Less error-prone

❌ Cons :

• Less control over iteration logic
• Not suitable if you need complex iteration behavior

Using Iterator (Fine-Grained Control)

If you need full control over how iteration procedures (eg, lazy loading, computed values, or complex data structures), implement the Iterator interface directly.

It requires five methods:

• current() – returns the current element
• key() – returns the current key
• next() – moves to the next element
• rewind() – resets the iterator to the beginning
• valid() – checks if the current position is valid

Here's an example of a custom iterator that lazy generates even numbers:

 class EvenNumberGenerator implements Iterator
{
    private int $current;
    private int $max;
    private int $position;

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

    public function rewind(): void
    {
        $this->current = 0;
        $this->position = 0;
    }

    public function current(): int
    {
        return $this->current;
    }

    public function key(): int
    {
        return $this->position;
    }

    public function next(): void
    {
        $this->current = 2;
        $this->position ;
    }

    public function valid(): bool
    {
        return $this->current <= $this->max;
    }
}

Usage:

 $evens = new EvenNumberGenerator(10);

foreach ($evens as $index => $value) {
    echo "[$index] => $value" . PHP_EOL;
}

Output:

 [0] => 0
[1] => 2
[2] => 4
[3] => 6
[4] => 8
[5] => 10

✅ Pros :

• Full control over iteration process
• Can support lazy evaluation, infinite sequences, or dynamic data
• Efficient for large or generated datasets

❌ Cons :

• More boilerplate code
• Risk of bugs if state management is incorrect

When to Use Which?

• Use IteratorAggregate when your object wraps a collection or you can delegate iteration to another object. It's cleaner and safer.
• Use Iterator when you need custom iteration logic, such as filtering on-the-fly, generating values, or managing complex internal state.

You can even combine both — for example, having a class implement IteratorAggregate that returns a custom Iterator instance for advanced logic.

A Note on Traversable

Both Iterator and IteratorAggregate extend Traversable (though not directly — it's a built-in engine interface). This means any class implementing either can be used in foreach . However, Traversable cannot be implemented directly; you must use one of the two.

Basically, chosen based on your needs: wrap and reuse with IteratorAggregate , or build from scratch with Iterator .

The above is the detailed content of Implementing `Iterator` and `IteratorAggregate` for Custom Object Iteration. For more information, please follow other related articles on the PHP Chinese website!