IteratorAggregate lets a collection return another Traversable from getIterator() instead of implementing cursor methods itself.
The examples below begin with the core behavior, then move to an application-oriented use.
How Implementing IteratorAggregate Works
IteratorAggregate lets a collection return another Traversable from getIterator() instead of implementing cursor methods itself.
Example 1: Basic Usage
This example uses a small input to make the main behavior visible.
<?php
class Labels implements IteratorAggregate { public function getIterator(): Traversable { return new ArrayIterator(["draft", "live"]); } }
foreach (new Labels() as $label) { echo $label . " "; }Output:
draft live IteratorAggregate lets a collection return another Traversable from getIterator() instead of implementing cursor methods itself.
Example 2: A Different Input
A different set of values shows the same operation in another situation.
<?php
class Numbers implements IteratorAggregate { public function getIterator(): Traversable { yield 10; yield 20; } }
echo iterator_count((new Numbers())->getIterator());Output:
2Return a fresh iterator when repeatable traversal is required; a single consumed generator cannot be reused.
Practical Example: Applying the Feature
This example shows an application-style use of the feature, with its surrounding setup visible.
<?php
final class UserCollection implements IteratorAggregate { public function __construct(private array $users) {} public function getIterator(): Traversable { yield from $this->users; } }
foreach (new UserCollection(["Alex", "Sam"]) as $user) { echo $user . "\n"; }Output:
Alex
SamThe code is shown for learning. Adjust the class names, inputs and error handling to suit your application.
Important Behavior and Edge Cases
- Return a fresh iterator when repeatable traversal is required; a single consumed generator cannot be reused.
- IteratorAggregate lets a collection return another Traversable from getIterator() instead of implementing cursor methods itself.
- Observe differences in empty inputs, invalid states and optional extension availability where relevant.
Comparison With Related Approaches
| Approach | Important Difference |
|---|---|
Implementing IteratorAggregate | IteratorAggregate lets a collection return another Traversable from getIterator() instead of implementing cursor methods itself. |
| Alternative approach | Iterator requires five cursor methods, while IteratorAggregate only requires getIterator(). |
Common Beginner Mistakes
| Mistake | Correct Approach |
|---|---|
Ignoring the documented state or precondition of Implementing IteratorAggregate | Return a fresh iterator when repeatable traversal is required; a single consumed generator cannot be reused. |
| Expecting a different type of result | Read the declared return type and distinguish returned values from changes to the source object. |
| Assuming a related API works identically | Iterator requires five cursor methods, while IteratorAggregate only requires getIterator(). |
Key Takeaways
- IteratorAggregate lets a collection return another Traversable from getIterator() instead of implementing cursor methods itself.
- Return a fresh iterator when repeatable traversal is required; a single consumed generator cannot be reused.
- Use the example that matches the values, runtime version and dependencies in your application.
Implementing IteratorAggregate is useful when its behavior matches the data structure and lifecycle of your PHP application. Choose it with a clear understanding of its preconditions and returned values.