Saving Iterator is a true caching iterator for PHP. It aims to solve the same problems as PHP's Caching Iterator but with a better encapsulation of data in mind. It has properties of both Iterator and array.

How to use

Require it with Composer:

composer require maxgoryunov/saving-iterator

Then include this in your index.php or any other main file:

require __DIR__ . "./vendor/autoload.php";

If you have any questions, ask them at Discussions.

Decorating Iterators

In order to use SavingIterator you need to provide a source and a target. Any object with Iterator interface is a suitable source. Target needs to be an AddingIterator(usually ArrayAddingIterator is enough):

$squares = new SavingIterator(
    new SquaringIterator(
        [1, 2, 3, 4, 5, 6]
    ),
    new ArrayAddingIterator()
);

It is also possible to use SavingIterator without providing a target. In this case, it will use a default AddingIterator storage:

$squares = new SavingIterator(
    new SquaringIterator(
        [1, 2, 3, 4, 5, 6]
    )
);

If the origin object is not an Iterator then wrap it in TransparentIterator:

$wrapped = new SavingIterator(
    new TransparentIterator($origin),
    new ArrayAddingIterator()
);

If you do not want to store nulls in your AddingIterator then use ValidAddingIterator:

$valid = new ValidAddingIterator(
    new ArrayAddingIterator()
);

Decorating Generators

You can also use it with Generators. If the iterator is called twice, rewind exception will not be thrown. Just pass a function which returns a Generator to the constructor:

$numerals = function (): Generator {
    for ($i = 0; $i < 10; $i++) {
        yield $i;
    }
};

$iter = new SavingIterator(
    $numerals,
    new ArrayAddingIterator()
);

How to run tests

First, install Docker. After that, run:

docker-compose build

docker-compose run --rm php bash

After you start the container, install dependencies and run tests:

composer install

vendor/bin/phpunit tests

How to contribute

Fork this repository, then create a folder for it and install Composer if you do not have it.

Clone this repository:

git clone https://github.com/MaxGoryunov/saving-iterator

Then run:

composer install

This command will install all dependencies required for development. Make changes and open a pull request. Your PR will be reviewed and accepted if it does not fail our build.