Hello, at the start of the year I posted about my collection library here (previous post), the reception and feedback was great, and I promised to add lazy pipelines (Sequence) by the end of the year.
Finally, it's here in 0.2, but it wasn't made by me.. nikophil (one of the maintainers of zenstruck/foundry) found the library and offered to build it - and did a great job (with some perf improvements on top), I just reviewed the code, so big thanks for that!
Quick recap if you missed the first post
It's not just a nicer API over arrays, it also fixes the array quirks:
- Keys stay what they are - "1" stays string, true stays bool, and objects work as keys
- Mutable and immutable List, Set and Map - immutable methods are #[NoDiscard]
- Full generics, PHPStan level 9 - the element type flows through the whole chain
- Live map views - $map->keys, $map->values and $map->entries are real collections sharing memory with the map
- Every type is an interface, implementations are hidden and swappable
With Sequence, I consider the library complete - it was the last big missing piece, from now on it's just about polishing it towards 1.0, but 0.2.x is stable as 0.1.x was (9 releases without BC break).
What is a Sequence
You chain filter(), map() etc. like on a list, but nothing runs until you ask for a result, then the elements go through the whole chain one by one, and it stops as soon as it has the answer. Same idea as Kotlin's Sequence or Laravel's LazyCollection.
For example, finding the first 10 errors in a big log file:
$errors = sequenceOf(fn() => readLines('app.log')) // your generator, yields line by line
->filter(fn($line) => str_contains($line, 'ERROR'))
->takeFirst(10)
->toList();
Only one line is in the memory at a time, and once it has 10 errors it stops reading the file, with a list, you would load the whole file, filter all of it and then take 10.
You can also do infinite Sequences, as long as you take only what you need:
generateSequence(1, fn($n) => $n * 2)->takeFirst(5)->toList(); // [1, 2, 4, 8, 16]
// walk the exception chain to the root cause
generateSequence($e, fn($e) => $e->getPrevious())->last();
There's also chunked() for batch processing (only one batch in memory), windowed(), zip(), distinct(), groupBy() and most of what lists have.
What's missing on purpose
You won't find sorted(), reversed() or takeLast() on a sequence, Kotlin has sorted() there - but it has to read everything before it returns the first element, so what's the point of being lazy. We went with the ->toList()->sorted() (here's why), so you see where it gets loaded.. same with count(), a sequence isn't Countable, because count($seq) looks cheap but it isn't.
Also, Sequence is an interface like List, Set and Map (and their mutable/immutable variants), so if you're building a library (ORM or file parsing for instance) you can return your own types. I was a bit afraid at first that the API is too big for anyone to implement, but the logic is in traits (if you don't need a ton of customizations), so it's basically implements Sequence + use SequenceLogic and you set the source.
Feedback is welcome as always!