loophp / iterators
The missing PHP iterators.
Fund package maintenance!
drupol
Installs: 183 096
Dependents: 3
Suggesters: 0
Security: 0
Stars: 35
Watchers: 3
Forks: 6
Open Issues: 1
Requires
- php: >= 8.1
Requires (Dev)
- ext-pcov: *
- drupol/php-conventions: ^5
- phpbench/phpbench: ^1.2
- phpstan/phpstan-strict-rules: ^1.0
- phpunit/php-code-coverage: ^10
- phpunit/phpunit: ^10
Suggests
- ext-mbstring: For UTF-8 support in the StringIteratorAggregate.
- dev-main
- 3.2.1
- 3.2.0
- 3.1.1
- 3.1.0
- 3.0.2
- 3.0.1
- 3.0.0
- 2.5.1
- 2.5.0
- 2.4.0
- 2.3.5
- 2.3.4
- 2.3.3
- 2.3.2
- 2.3.1
- 2.3.0
- 2.2.0
- 2.1.0
- 2.0.1
- 2.0.0
- 1.6.13
- 1.6.12
- 1.6.11
- 1.6.10
- 1.6.9
- 1.6.8
- 1.6.7
- 1.6.6
- 1.6.5
- 1.6.4
- 1.6.3
- 1.6.2
- 1.6.1
- 1.6.0
- 1.5.14
- 1.5.13
- 1.5.12
- 1.5.11
- 1.5.10
- 1.5.9
- 1.5.8
- 1.5.7
- 1.5.6
- 1.5.5
- 1.5.4
- 1.5.3
- 1.5.2
- 1.5.1
- 1.5.0
- 1.4.0
- 1.3.1
- 1.3.0
- 1.2.2
- 1.2.1
- 1.2.0
- 1.1.1
- 1.1.0
- 1.0.0
This package is auto-updated.
Last update: 2024-12-21 12:35:14 UTC
README
PHP Iterators
Description
The missing PHP iterators.
Features
CachingIteratorAggregate
ChunkIterableAggregate
ClosureIterator
:ClosureIterator(callable $callable, array $arguments = [])
ClosureIteratorAggregate
:ClosureIteratorAggregate(callable $callable, array $arguments = [])
ConcatIterableAggregate
FilterIterableAggregate
InterruptableIterableIteratorAggregate
:InterruptableIterableIteratorAggregate(iterable $iterable)
IterableIterator
:IterableIterator(iterable $iterable)
IterableIteratorAggregate
:IterableIteratorAggregate(iterable $iterable)
MapIterableAggregate
MersenneTwisterRNGIteratorAggregate
MultipleIterableAggregate
PackIterableAggregate
PausableIteratorAggregate
RandomIterableAggregate
RecursiveIterableAggregate
ReductionIterableAggregate
ResourceIteratorAggregate
SimpleCachingIteratorAggregate
SortIterableAggregate
StringIteratorAggregate
TypedIterableAggregate
UniqueIterableAggregate
UnpackIterableAggregate
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.
ChunkIterableAggregate
<?php $iterator = (new ChunkIterableAggregate( range('a', 'j'), 2 )); foreach ($iterator as $chunk) {} // ['a', 'b'], ['c', 'd'], ...
FilterIterableAggregate
<?php $iterator = (new FilterIterableAggregate( range(0, 5), static fn (int $v, int $key, iterable $iterable): bool => 0 === (($v + 2 * $key + count($iterable)) % 2) )); foreach ($iterator as $filteredValue) {} // 0, 2, 4
InterruptableIterableIteratorAggregate
Let you break the iterator at anytime.
Useful when working with infinite collection of items.
<?php // Generator $naturals = static function () { $i = 0; while (true) { yield $i++; } }; $iterator = new InterruptableIterableIteratorAggregate($generator()); foreach ($iterator as $generator => [$key, $value]) { var_dump($value); if (10 === $value) { $generator->send(InterruptableIterableIteratorAggregate::BREAK); } }
MapIterableAggregate
<?php $iterator = (new MapIterableAggregate( range('a', 'c'), static fn (string $letter, int $key, iterable $iterable): string => sprintf( '%s::%s::%s', $key, $letter, gettype($iterable) ) )); foreach ($iterator as $tranformedValue) {}
MersenneTwisterRNGIteratorAggregate
<?php $rngGenerator = (new MersenneTwisterRNGIteratorAggregate()) ->withMin(1) ->withMax(10) ->withSeed($seed); foreach ($rngGenerator as $randomValue) {} // Random integers in [1, 10]
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'] */
UniqueIterableAggregate
<?php $generator = static function(): Generator { while (true) { yield mt_rand(0, 9); } }; $iterator = new UniqueIterableAggregate($generator(), 1000); foreach ($iterator as $value) {} // 9 random values only.
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); }
RecursiveIterableAggregate
This iterator allows you to iterate through tree-like structures by simply
providing an iterable
and callback to access its children.
<?php $treeStructure = [ [ 'value' => '1', 'children' => [ [ 'value' => '1.1', 'children' => [ [ 'value' => '1.1.1', 'children' => [], ], ], ], [ 'value' => '1.2', 'children' => [], ], ], ], [ 'value' => '2', 'children' => [], ], ]; $iterator = new RecursiveIterableAggregate( $treeStructure, fn (array $i) => $i['children'] ); foreach ($iterator as $item) { var_dump($item['value']); // This will print '1', '1.1', '1.1.1', '1.2', '2' }
ReductionIterableAggregate
<?php $iterator = (new ReductionIterableAggregate( range(0, 10), static fn (int $carry, int $value, int $key, iterable $iterable): int => $carry + $value, 0 )); foreach ($iterator as $reduction) {} // [0, 1, 3, 6, 10, 15, 21, 28, 36, 45, 55]
SortIterableAggregate
Implements a stable sort iterable aggregate
This means that if two elements have the same key, the one that appeared earlier in the input will also appear earlier in the sorted output.
$valueObjectFactory = static fn (int $id, int $weight): object => new class($id, $weight) { public function __construct(public readonly int $id, public readonly int $weight) {} }; $input = [ $valueObjectFactory(id: 1, weight: 1), $valueObjectFactory(id: 2, weight: 1), $valueObjectFactory(id: 3, weight: 1), ]; $sort = new SortIterableAggregate( $input, static fn (object $a, object $b): int => $a->weight <=> $b->weight );
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.
Static analyzers are also controlling the code. PHPStan and PSalm are enabled to their maximum level.
Contributing
Feel free to contribute by sending pull requests. We are a usually very responsive team and we will help you going through your pull request from the beginning to the end.
For some reasons, if you can't contribute to the code and willing to help, sponsoring is a good, sound and safe way to show us some gratitude for the hours we invested in this package.
Sponsor me on Github and/or any of the contributors.
Changelog
See CHANGELOG.md for a changelog based on git commits.
For more detailed changelogs, please check the release changelogs.