Download the PHP package blueprintau/collections without Composer

BlueprintAU Collections

A pure, standalone array wrapper for the BlueprintAU ecosystem. This is the generic collection package — no model imports, no framework coupling. It is the one package every other BlueprintAU package can depend on without circularity.

Dependencies

None. This is a pure, standalone array wrapper.

Installation

Usage

The Enumerable contract

Enumerable is the contract both Collection and LazyCollection implement. It extends \IteratorAggregate and \JsonSerializable, so any collection is foreach-able and json_encode()-able.

Only methods that behave identically whether the data is eagerly in memory or lazily streamed belong on the contract. Anything that forces materialization (count, sort, unique, toArray) stays on Collection.

The LazyCollection

LazyCollection is the lazy counterpart to Collection. Instead of holding items in memory, it streams them through a generator source on demand.

• Transforms are lazy — map, filter, pluck, take, skip, slice, and friends return a new LazyCollection that pulls from the previous one only when iterated. This makes it possible to work with infinite or very large sources without materializing them.
• Terminal operations materialize — toArray, count, toJson, all, sort, sortBy, unique, and reverse consume the stream.
• Re-iterable — the source is stored as a factory closure, so each iteration produces a fresh generator. Pass a callable source (e.g. a generator function) to replay the stream. Non-callable sources are wrapped via yield from, which rewinds re-iterable iterators (e.g. ArrayIterator) automatically. A raw Generator is single-use: iterating it twice throws a "Cannot rewind a generator that was already run" exception rather than silently returning wrong data.

Memory and concurrency contracts

• Memory model — transforms are O(1) memory: each item is pulled, processed, and released. Operations that inherently need the whole stream accumulate internally: count, sort, sortBy, reverse, toArray, toJson, all, groupBy, and unique (which keeps a "seen" set that grows with the number of distinct values). take/skip/slice with negative arguments must reach the end of the stream and materialize internally. On an infinite source, any accumulating operation will run forever or exhaust memory — there is no guard; prefer take() to bound infinite streams before applying terminal operations.
• Concurrency model — a LazyCollection is not safe for concurrent iteration. Each getIterator() call produces a fresh generator from the source factory, but two consumers iterating the same underlying single-use source (e.g. a shared raw Generator, a socket, a cursor) will silently split its items between them — each item goes to exactly one consumer, with no error. This applies through transforms too: a mapped or filtered view shares the parent's source. Iterate a LazyCollection from one consumer at a time, or wrap a shared source in a caching layer before handing it to multiple consumers.
• Immutability — Collection is immutable: writes through ArrayAccess ($collection[$k] = $v, unset($collection[$k])) throw a BadMethodCallException. Transforms return new instances. Note that immutability is shallow: the collection never mutates its own structure, but mutable elements (objects, arrays) are shared by reference between the original and derived collections — mutating an element mutates it everywhere. Subclasses that add mutable state must preserve the transform-immutability contract themselves.

Requirements

PHP 8.4 or newer.

Testing

CI runs the test suite across PHP 8.4 / 8.5 (lowest and highest dependencies) on every push and pull request. Releases are cut from the Release workflow (Actions → Release), which takes a version tag, verifies it does not already exist, runs the full test suite, then creates the tag and GitHub Release.

License

MIT