PHP Iterators
Description
The missing PHP iterators.
Features
CachingIteratorAggregateClosureIterator:ClosureIterator(callable $callable, array $arguments = [])ClosureIteratorAggregate:ClosureIteratorAggregate(callable $callable, array $arguments = [])IterableIterator:IterableIterator(iterable $iterable)IterableIteratorAggregate:IterableIteratorAggregate(iterable $iterable)PackIterableAggregateUnpackIterableAggregatePausableIteratorAggregateRandomIterableAggregate
Installation
composer require loophp/iterators
Usage
CachingIteratorAggregate
Let you cache any iterator. You then get \Generators rewindable for free.
This implementation does not use internal state to keep track of the current position of the iterator. The underlying mechanism is based on SPL \CachingIterator.
The pros of using that iterator is performance. It's blazing fast, it cannot compare to any other stateful custom implementations.
This iterator will cache keys and values, of any type.
<?php
// Generator
$generator = static function (): \Generator {
yield true => 'foo';
yield false => 'bar';
yield ['foo', 'bar'] => 'foobar';
};
$iterator = new CachingIteratorAggregate($generator());
foreach ($iterator as $key => $value); // This will work.
foreach ($iterator as $key => $value); // This will also work.
PackIterableAggregate
<?php
// Generator
$generator = static function (): \Generator {
yield true => 'foo';
yield false => 'bar';
yield ['foo', 'bar'] => 'foobar';
};
$iterator = new PackIterableAggregate($generator());
foreach ($iterator as $value);
/*
$value will yield the following values:
- [true, 'foo']
- [false, 'bar']
- [['foo', 'bar'], 'foobar']
*/
UnpackIterableAggregate
<?php
// Generator
$generator = static function (): \Generator {
yield [true, 'foo'];
yield [false, 'bar'];
yield [['foo', 'bar'], 'foobar'];
};
$iterator = new UnpackIterableAggregate($generator());
foreach ($iterator as $key => $value);
/*
$key and $value will yield the following values:
- true => 'foo'
- false => 'bar'
- ['foo', 'bar'] => 'foobar'
*/
ClosureIterator
<?php
$callable = static fn (int $from, int $to) => yield from range($from, $to);
$iterator = new ClosureIterator($callable(10, 20));
IterableIterator
<?php
$iterator = new IterableIterator(range(1, 10));
PausableIteratorAggregate
<?php
$inputIterator = new ArrayIterator(range('a', 'e'));
$iteratorAggregate = new PausableIteratorAggregate($inputIterator);
$i = 0;
foreach ($iteratorAggregate as $v) {
var_dump($v) // Print: 'a', 'b', 'c'
if (++$i === 2) {
break;
}
}
foreach ($iteratorAggregate->rest() as $v) {
var_dump($v) // Print: 'd', 'e'
}
RandomIterableAggregate
In order to properly use this iterator, the user need to provide an extra parameter seed. By default, this parameter is set to zero and thus, the resulting iterator will be identical to the original one.
Random items are selected by choosing a random integer between zero and the value of seed. If that value is zero, then the iterator will yield else it will skip the value and start again with the next one.
The bigger the seed is, the bigger the entropy will be and the longer it will take to yield random items. It's then up to the user to choose an appropriate value. Usually a good value is twice the approximate amount of items the decorated iterator has.
If you're willing to iterate multiple times on this, use the CachingIteratorAggregate to cache the results.
This iterator works on keys and values, of any type.
<?php
$seed = random_int(0, 1000);
$inputIterator = new ArrayIterator(range('a', 'e'));
$iterator = new RandomIterableAggregate($inputIterator, $seed);
foreach ($iterator as $v) {
var_dump($v);
}
$iterator = new CachingIteratorAggregate(
(new RandomIterableAggregate($inputIterator, $seed))->getIterator()
);
foreach ($iterator as $v) {
var_dump($v);
}
foreach ($iterator as $v) {
var_dump($v);
}
Code quality, tests, benchmarks
Every time changes are introduced into the library, Github runs the tests.
The library has tests written with PHPUnit. Feel free to check them out in the tests directory.
Before each commit, some inspections are executed with GrumPHP; run composer grumphp to check manually.
The quality of the tests is tested with Infection a PHP Mutation testing framework - run composer infection to try it.
Static analyzers are also controlling the code. PHPStan and PSalm are enabled to their maximum level.
Contributing
Feel free to contribute by sending Github pull requests. I'm quite responsive :-)
If you can't contribute to the code, you can also sponsor me on Github.
Changelog
See CHANGELOG.md for a changelog based on git commits.
For more detailed changelogs, please check the release changelogs.
![[WIP] Introduce PaginatingIterator](https://avatars.githubusercontent.com/u/34811569?v=4)
465 Dec 30, 2022
121 Jan 6, 2023
1.4k Dec 30, 2022
629 Nov 20, 2022
436 Jan 3, 2023
430 Jan 5, 2023
191 Dec 19, 2022
62 Dec 27, 2021
610 Jan 2, 2023
370 Dec 29, 2022
9 Aug 21, 2022
1k Dec 27, 2022
0 May 16, 2022
67 Jun 24, 2022
16 Nov 18, 2022
462 Dec 30, 2022
82 Nov 11, 2022
34.4k Jan 1, 2023
11.3k Dec 31, 2022