Download the PHP package noctud/collection without Composer

Noctud Collection

Type-safe, mutable/immutable, sortable and key-preserving List/Map/Set collections for PHP 8.4+.

✨ Features

• Type-safe: Full generics support. Static analyzers understand every element type through the chain.
• Key-preserving: Map keys like float, bool or "1" retain their original types. No silent type casting.
• Object keys: Use objects as map keys out of the box. Implement Hashable for custom identity semantics.
• Mutable & Immutable: Choose the right variant. Immutable methods are marked with #[NoDiscard].
• Lazy Init: Construct collections from closures. Uses PHP 8.4 lazy objects — materialized only on first access.
• Interface-driven: Every type is an interface. Factory functions return contracts, not concrete classes.
• Expressive: Rich set of higher-order functions — map, filter, sorted, flatMap, groupBy, partition, and more.
• Chainable: Mutating methods return a collection — read result like $set->tracked()->add('a')->changed.
• Strict: Choose between throwing and nullable methods (get/getOrNull, first/firstOrNull, etc.)
• Inspired by Kotlin: Factory functions, mutable/immutable split, OrNull conventions, and namings.

🗺️ Architecture

Full architecture is shown in docs, there are also Writable interfaces for easy third party implementations.

🏗️ Constructing

Use factory functions from namespace Noctud\Collection.

Use stringMapOf/mutableStringMapOf and intMapOf/mutableIntMapOf for better performance and ~50% less memory — they use single-array storage and enforce key types at runtime.

📖 Accessing

Array access is strict by default — throws on missing keys/indices. Use ?? for safe fallback.

Sets support only the contains method, they have no array access by design.

🌪️ Filtering & transformations

All transformation methods (filter, map, flatMap, zip, partition, ...) always return a new immutable collection, regardless of whether the source is mutable or immutable. Unlike array_filter, Lists are always reindexed — no gaps, no need for array_values().

📊 Sorting

Every Collection and Map is sequentially ordered, so sorting is supported everywhere.

• sorted* returns a new collection, sort* sorts in place (Mutable only).
• *By takes a selector, *With takes a comparator. Add Desc for descending.

👁️ Map views

Every Map exposes live read-only $keys, $values, and $entries views. These are real Set and Collection objects backed by the same underlying store — mutations to the map are immediately visible through views and vice versa.

✔️ Quantifiers

Check if all/any or none of the elements match the predicate.

➰ Iterating

All collections are traversable.

⛓️ Chainable

Mutating methods return $this (Mutable) or a new instance (Immutable). Both share the same API, but immutable methods are marked with #[NoDiscard] to prevent accidental misuse.

Method tracked() wraps a mutable collection in a proxy that tracks changes. The $changed flag is available on the return value of each mutation method, not on the wrapper itself.

🛡️ Type safety

Mutable collections enforce strict typing — PHPStan warns if you try to add elements of incompatible types. Immutable collections allow type widening since they return a new instance with potentially different types.

🔑 Preserving key types

Map will always preserve original keys, you have to only worry about constructing the map.

💤 Lazy Initialization

Construct from a closure — the callback executes only on first access. Under the hood, lazy collections use PHP 8.4's Lazy Objects — the internal store is a ghost proxy materialized only when first accessed.

Lazy collections behave identically to eager ones — there is no way to tell from outside. Always construct lazy collections using closures, not Generator objects directly.

㊙️ Objects as keys

Use objects as map keys out of the box. By default, objects are hashed using spl_object_id.

Implement Hashable for custom identity semantics:

🧩 Extending

Every type you interact with is an interface — ImmutableList, MutableMap, Set, even MapEntry. Logic is encapsulated in traits, so you can turn any class into a collection.

For custom stores, database-backed collections, and more, see the Extending guide.

🚀 Performance

This library prioritizes type safety and correctness. Lists and Sets have minimal overhead compared to native arrays. The generic mapOf() uses dual-array storage to preserve any key type, which adds memory and performance overhead.

When keys are exclusively strings or integers, use the optimized variants for maximum performance:

These use single-array storage, skip key hashing entirely, and use ~50% less memory than mapOf().

Converting between mutable and immutable via toMutable()/toImmutable() uses copy-on-write — the data is shared until either side is modified, making variant switching virtually free.

🔎 Static analysis

Generics are fully supported by PHPStan and Psalm. PhpStorm has known limitations with generics inference.

📚 Documentation

• Getting started — Installation, architecture, basic usage
• List / Set / Map — Type guides with examples
• Mutability — Mutable vs immutable, change tracking, copy-on-write
• Sorting — Full sorting reference with quick-reference table
• Lazy collections — Deferred initialization
• Extending — Custom implementations, stores, traits
• API reference — All method signatures