How to Write Your Own Iterable Objects in PHP

PHP lets you create iterable gadgets. Those can be utilized inside of loops as a substitute of scalar arrays. Iterables are frequently used as object collections. They let you typehint that object whilst holding reinforce for looping.

Easy Iteration

To iterate over an array in PHP, you utilize a foreach loop:

foreach (["1", "2", "three"] as $i) 
    echo ($i . " ");

This case would emit 1 2 three.

You’ll be able to additionally iterate over an object:

$cls = new StdClass();
$cls -> foo = "bar";
foreach ($cls as $i) 

This case would emit bar.

The Assortment Downside

For elementary categories with public homes, a simple foreach works neatly. Let’s now believe every other magnificence:

magnificence UserCollection 
    safe array $pieces = [];
    public serve as upload(UserDomain $consumer) : void 
        $this -> pieces[] = $consumer;
    public serve as containsAnAdmin() : bool 

This magnificence represents a choice of UserDomain cases. As PHP doesn’t reinforce typed arrays, categories like this are important when you need to typehint an array which is able to best hang one form of price. Collections additionally let you create application strategies, like containsWithAdmin, that facilitate herbal interplay with array pieces.

Sadly, seeking to iterate over this assortment gained’t give the required effects. Preferably, iterating will have to function at the $pieces array, no longer the category itself.

Imposing Iterator

Herbal iteration will also be added the usage of the Iterator interface. Via enforcing Iterator, you’ll be able to outline PHP’s behaviour when cases of your magnificence are used with foreach.

Iterator has 5 strategies which you’ll wish to enforce:

  • present() : combined – Get the article on the present place within the iteration.
  • key() : scalar – Get the important thing on the present place within the iteration.
  • subsequent() : void – Transfer to the following place within the iteration.
  • rewind() : void – Rewind the placement to the beginning of the iteration.
  • legitimate() : bool – Get whether or not the present place has a price.

Those strategies could be complicated to start with. Imposing them is easy although – you’re specifying what to do at every level of a foreach execution.

Each and every time your object is used with foreach, rewind() will probably be known as. The legitimate() approach is known as subsequent, informing PHP whether or not there’s a price on the present place. If there’s, present() and key() are known as to get the price and key at that place. After all, the subsequent() approach is known as to advance the placement pointer. The loop returns to calling legitimate() to look if there’s every other merchandise to be had.

Right here’s an ordinary implementation of Iterator:

magnificence DemoIterator 
    safe int $place = zero;
    safe array $pieces = ["cloud", "savvy"];
    public serve as rewind() : void 
    public serve as present() : string 
        echo "Present";
        go back $this -> pieces[$this -> place];
    public serve as key() : int 
        echo "Key";
        go back $this -> place;
    public serve as subsequent() : void 
        echo "Subsequent";
        ++$this -> place;
    public serve as legitimate() : void 

Right here’s what would occur when iterating DemoIterator:

$i = new DemoIterator();
foreach ($i as $key => $price) 
    echo "$key $price";

// Rewind
// Legitimate Present Key
// zero cloud
// Subsequent
// Legitimate Present Key
// 1 savvy
// Subsequent
// Legitimate

Your iterator must care for a document of the loop place, take a look at whether or not there’s a component on the present loop place (by the use of legitimate()) and go back the important thing and worth on the present place.

PHP gained’t attempt to get admission to the important thing or price when the loop place is invalid. Returning false from legitimate() instantly terminates the foreach loop. Most often, this will probably be whilst you get to the top of the array.


Writing iterators briefly will get repetitive. Maximum observe the precise recipe proven above. IteratorAggregate is an interface which is helping you briefly create iterable gadgets.

Enforce the getIterator() approach and go back a Traversable (the bottom interface of Iterator). It is going to be used because the iterator when your object is used with foreach. That is normally one of the simplest ways so as to add iteration to a suite magnificence:

magnificence UserCollection implements IteratorAggregate 
    safe array $pieces = [];
    public serve as upload(UserDomain $Consumer) : void 
        $this -> pieces[] = $consumer;
    public serve as getIterator() : Traversable 
        go back new ArrayIterator($this -> pieces);

$customers = new UserCollection();
$customers -> upload(new UserDomain("James"));
$customers -> upload(new UserDomain("Demo"));
foreach ($customers as $consumer) 

When running with collections, 3 strains of code are normally all you wish to have to setup iteration! An ArrayIterator is returned because the Traversable. It is a magnificence which mechanically creates an Iterator out of an array. You’ll be able to now iterate over the logical values inside of your object, as a substitute of the article’s direct homes.

The use of Prebuilt PHP Iterators

You’ll wish to write your personal iterators in case you have complicated good judgment. It’s infrequently important to start out from scratch as PHP ships with a number of complicated iterators supplied via SPL.

The integrated categories come with DirectoryIterator, FilesystemIterator, GlobIterator and quite a lot of recursive iterators. Right here’s one of the most dear generic iterators.


The LimitIterator allows you to iterate over a subset of an array. You don’t wish to splice the array first or manually stay observe of place inside of your foreach.

$arr = new ArrayIterator(["a", "b", "c", "d"]);
foreach (new LimitIterator($arr, zero, 2) as $val) 

This case would emit a b. Observe that LimitIterator accepts every other Iterator, no longer an array. The instance makes use of ArrayIterator, the integrated magnificence which constructs an Iterator from an array.


InfiniteIterator by no means terminates the loop, so that you’ll wish to ruin from it manually. Another way, the iterator mechanically wraps again to the beginning of the array when it reaches the top.

This iterator is especially helpful when running with time-based values. Right here’s a very easy approach of establishing a three-year calendar, which additionally makes use of the LimitIterator described above:

$months = [
    "Jan", "Feb", "Mar", "Apr", "Might", "Jun",
    "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
$limitless = new InfiniteIterator(new ArrayIterator($months));
foreach (new LimitIterator($limitless, zero, 36) as $month) 
    echo $month;

This emits 3 years’ value of months.


FilterIterator is an summary magnificence which you will have to lengthen. Enforce the settle for technique to clear out undesirable values which will have to be skipped all over iteration.

magnificence DemoFilterIterator extends FilterIterator 
$demo = new DemoFilterIterator();
foreach ($demo as $val) 

This case would emit 1 four three.

The array values which can be upper than five are filtered out and don’t seem within the foreach.

The “iterable” form

From time to time you could write a generic serve as that makes use of a foreach loop however is aware of not anything in regards to the values it’ll be iterating over. One instance is an summary error handler which merely dumps the values it receives.

You’ll be able to typehint iterable in those eventualities. It is a pseudo-type which can settle for both an array or any object enforcing Traversable:

serve as handleBadValues(iterable $values) : void 

The iterable form is so imprecise that you simply will have to think twice earlier than the usage of it. However, it may be helpful as a last-resort form if you wish to have to ensure an enter price will paintings with foreach.


Applying iterators is helping you write blank code that’s extra modular. You’ll be able to transfer strategies that act on arrays of gadgets into devoted assortment categories. Those can then be typehinted personally whilst closing totally suitable with foreach.

More often than not, including iteration reinforce will also be accomplished via enforcing IteratorAggregate and returning an ArrayIterator configured with the pieces for your assortment. PHP’s different iterator varieties, which have a tendency to head unused via builders, can very much simplify extra explicit loops. They provide complicated logical behaviours with out requiring guide pointer monitoring for your foreach commentary.

Leave a Reply

Your email address will not be published. Required fields are marked *