Forem: delacry

PHP 8.5's pipe operator and the array stdlib problem

delacry — Thu, 30 Apr 2026 11:44:39 +0000

PHP 8.5 shipped a pipe operator, from Larry Garfield's RFC (approved 33-7). The marketing examples look great:

$slug = $title
    |> trim(...)
    |> strtolower(...);

Reads top to bottom, no nesting, types flow. For chains of single-input transformations, which is what the RFC was explicit about targeting, the operator does exactly what you'd want.

The friction starts when you reach for it on PHP's array stdlib, which is where most day-to-day chaining happens. Most of what follows isn't really a flaw in the pipe operator itself. It's the stdlib's call-shape inconsistencies leaking through whatever composition mechanism you put on top of them.

The naive port

A common form-handling task: clean user-submitted tags and sort a-z.

$cleanTags = array_values(
    array_filter(
        array_map(fn($t) => strtolower(trim($t)), $rawTags),
        fn($t) => strlen($t) >= 3
    )
);
sort($cleanTags);

Three nested calls plus a trailing sort. It has to be its own statement because sort returns bool and mutates the array by reference. You read the nested part middle-out: array_map runs first, then array_filter, then array_values. Eyes parse opposite to execution.

The pipe operator should clean this up. Here's the rewrite:

$cleanTags = $rawTags
    |> (fn($ts) => array_map(fn($t) => strtolower(trim($t)), $ts))
    |> (fn($ts) => array_filter($ts, fn($t) => strlen($t) >= 3))
    |> array_values(...)
    |> (function ($ts) { sort($ts); return $ts; });

Better than the nested version. Reads top to bottom. But three things are happening here that the toy examples don't tell you about.

Gotcha 1: argument-order mismatch

array_map and array_filter take their arguments in different orders.

array_map(callable $callback, array $array, ...); // callable first
array_filter(array $array, ?callable $callback, ...); // array first

The pipe operator passes the left value as the first argument to whatever's on the right, so you can't first-class either function into a chain:

$result = $rawTags |> array_filter(...); // works, array is first arg
$result = $rawTags |> array_map(...); // broken, $rawTags lands as callback

To use array_map in a pipe, wrap it in an arrow function to swap the argument order. In the rewrite, both array_map and array_filter need a wrapper. array_map to swap arguments, array_filter to inject the predicate. Only array_values fits naturally because it's single-argument.

The pipe operator doesn't paper over the stdlib's inconsistencies; it makes them more visible. Every chain across array_map / array_filter / array_reduce ends up with this kind of glue in it.

Gotcha 2: arrow functions need parentheses

Look at the wrappers in the rewrite:

|> (fn($ts) => array_map(fn($t) => strtolower(trim($t)), $ts))

The parens around the arrow function are required, not stylistic. Without them, the arrow function "captures" everything to the end of the expression:

$result = $rawTags |> fn($ts) => array_map(...) |> array_values(...);

The parser reads that as the arrow function returning everything from array_map(...) through |> array_values(...). One stage, not two.

This was the edge case the 2025-08-28 RFC errata pinned down. The rule: wrap arrow functions in parens any time they appear in a pipe chain. Forget once and the bug is silent.

First-class callables (trim(...), strtolower(...)) avoid the issue because they're a single token, with no expression body for the parser to grab. The moment your chain has any non-unary stdlib function, though, you're back to writing (fn($x) => ...) over and over.

Gotcha 3: by-reference functions don't compose

That last step in the rewrite is uglier than the others for a reason:

|> (function ($ts) { sort($ts); return $ts; });

It can't be a one-liner arrow function, and it can't be a first-class callable. The RFC explicitly forbids first-class callables for any function whose first parameter is by-reference, which takes a long list of stdlib functions out of the pipe-able set:

$rawTags |> sort(...); // error: by-ref param
$rawTags |> array_walk(...); // same
$stack |> array_pop(...); // same

sort, rsort, usort, ksort, array_push, array_pop, array_shift, array_unshift, array_walk. All by-reference, all rejected. Most of the in-place array operations you'd reach for during a chain. The workaround is the full closure shown above: a function that mutates and returns. In practice you'll usually call sort outside the pipe and feed the result in.

Where the pipe operator actually shines

For chains of unary stdlib functions, the operator is exactly what you'd want:

$slug = $title
    |> trim(...)
    |> strtolower(...)
    |> (fn($s) => preg_replace('/[^a-z0-9]+/', '-', $s));

$payload = $body
    |> json_encode(...)
    |> gzencode(...)
    |> base64_encode(...);

Top to bottom, no argument-order gymnastics, the parens-around-arrow rule isn't a constant tax. String pipelines, encode/decode chains, math chains, hex round-trips. Anywhere the data is the first argument and the functions are unary, this is good code. __invoke objects and instance methods compose cleanly too, which is probably the use case the operator was actually designed for.

A coherent collection API does this naturally

The same tag-cleanup code with a collection library:

$cleanTags = listOf($rawTags)
    ->map(fn(string $t) => strtolower(trim($t)))
    ->filter(fn(string $t) => strlen($t) >= 3)
    ->sorted();

No wrappers, no parens-around-arrows, no array_values plumbing, no by-ref dance. PHPStan carries ImmutableList<string> all the way through. map(), filter(), and sorted() are methods, so the data is implicit (it's $this) and the callable is the first explicit argument every time.

The example uses noctud/collection, which is what I work on. Other collection libraries (illuminate/collections, doctrine/collections, ramsey/collection) solve the call-shape problem the same way at the method level. The point isn't the specific library; it's that a coherent method-chain API sidesteps the inconsistencies the pipe operator inherits from the stdlib.

The real fix would be native

The deeper issue is the stdlib itself. PHP's stdlib was never shaped for chaining. array_map and array_filter taking arguments in different orders is a 1995 design that calcified before anyone thought about composition. The pipe operator works around the symptom. Native methods on arrays and strings would fix the cause.

Nikita Popov's scalar_objects extension, from 2014, already showed what that could look like: $str->length(), $arr->map(...), methods directly on the primitives. It worked, and it's been sitting there as a proof of concept for over a decade. The reason it never made it to core is that as an extension, every userland library could register its own method set on the built-in types, trading the current inconsistency for a different one with composer-install collisions on top.

Doing it there means making the harder calls extensions get to dodge: which methods, what's the receiver, and the bigger question of whether array is really one type or two (a list and a map) wearing the same hat. Most modern languages split them. PHP didn't, and userland libraries (noctud/collection included) only paper over that conflation from outside the language. If core ever takes a serious run at native methods on arrays and strings, plus the harder design call of splitting array, that's the win the pipe operator alone can't deliver.

The takeaway

PHP 8.5's pipe operator is a real improvement. Use it for unary chains: string normalization, encode/decode pipelines, math, hex round-trips, pipelines of __invoke objects.

For array operations (anything involving array_map, array_filter, or by-reference functions like sort and array_walk), the operator inherits all of PHP's stdlib inconsistencies and adds an arrow-function-paren footgun on top. More readable than the nested version, but the readability gain shrinks once you've added all the wrappers. If your code spends most of its time chaining array operations, a collection library remains the cleaner answer.

PHP collection libraries in 2026: doctrine, illuminate, loophp, noctud, ramsey

delacry — Tue, 28 Apr 2026 14:20:11 +0000

If you've written PHP for any length of time, you've fought the array. It's a hash table, a list, a tuple, and an associative store all crammed into one type, and it silently casts your keys to whatever it feels like. Every serious project eventually reaches for something better. There are a few reasonable places to reach.

I wrote one of the five libraries this post covers (noctud/collection). I've tried to be fair, including pointing you at the right library when it isn't mine. Weigh that as you read.

The five contenders

doctrine/collections. The collections layer underneath Doctrine ORM. Mature, stable, present as a transitive dependency in a huge chunk of the PHP ecosystem.

illuminate/collections. Laravel's Collection class. Probably the most-installed PHP utility class that exists. Around 140 chainable helper methods, fluent API.

loophp/collection. Pol Dellaiera's lazy collection library, built around generators. FP-style, immutable, strong static analysis story.

noctud/collection. Modern PHP 8.4+ library. Separate mutable/immutable types, full generics, key-preserving Maps. Currently v0.1.1.

ramsey/collection. Ben Ramsey's standalone typed collection library. No framework dependency, runtime type enforcement, well-known beyond the Symfony/Laravel split.

A note on shape: most PHP "collections" are really maps

Before getting into the per-library breakdown, there's a structural distinction worth flagging that decides a lot of what follows.

PHP's array is a weird shape. It's both a list ([1, 2, 3]) and an associative map (['a' => 1, 'b' => 2]) at the same time, depending on what keys end up in it. Most PHP "collection libraries" inherit this and end up as a single Collection class that's really an array<TKey, TValue> wrapper underneath. There's no separate type for "list of items" or "set of unique items" or "key-value pairs"; there's just one Collection that happens to have keys you can choose to ignore.

Real collection design (the kind you see in Java, Kotlin, C#, Python, Rust) keeps these shapes separate:

List. Positional, indexed by 0-based int, duplicates allowed.
Set. Unique elements, no positional access.
Map. Key-value pairs, keys are unique.

The distinction isn't pedantic. It shapes the API in real ways:

// Single-Collection style (the array-wrapper approach)
$col = collect([1, 2, 3, 2]);
$col->forget(1); // removes AT INDEX 1, leaving [0 => 1, 2 => 3, 3 => 2]

// Distinct types
$list = listOf([1, 2, 3, 2]);
$list->removeAt(1); // [1, 3, 2] - by position
$list->removeElement(2); // [1, 3, 2] - by value, removes first match

$set = setOf([1, 2, 3]);
$set->removeElement(2); // {1, 3} - sets only do value-removal

$map = mapOf(['a' => 1, 'b' => 2]);
$map->remove('a'); // ['b' => 2] - by key, the only sensible meaning here

When a library only has one Collection type, it has to commit to one semantic for ambiguous operations and live with the confusion. Either remove() removes by key (which surprises List users) or by value (which surprises Map users). Iteration is the same: a Map should yield ($value, $key) pairs, a Set should yield $value only, a List should yield ($value, $index). Single-Collection libraries tend to yield ($value, $key) everywhere because that's the array shape, and the Set/List meaning gets lost.

Of the five libraries in this post, only ramsey/collection and noctud/collection are built around the real Set/List/Map separation. The other three are single-Collection types, varying in lazy-vs-eager and ergonomics but all sharing the array-wrapper shape underneath. That distinction is going to come up repeatedly in the per-library notes below.

Quick feature matrix

Feature	doctrine	illuminate	loophp	noctud	ramsey
PHP min	8.4 (3.x)	8.3	8.1	8.4	8.1
Real `List`/`Set`/`Map` types	❌	❌	❌	✅	✅
Sub-collections compose (`keys`/`values` are real collections)	❌	❌	❌	✅	❌
Full generic propagation	✅	❌	✅	✅	✅
Runtime type checks	❌	❌	❌	⚠️	✅
Mutable variant	✅	✅	❌	✅	✅
Immutable variant	❌	❌	✅	✅	❌
Non-string Map keys	❌	❌	❌	✅	❌
Lazy by default	❌	❌	✅	❌	❌
Change tracking	⚠️	❌	❌	✅	❌
Indices shift on removal	✅	⚠️	✅	✅	❌

✅ yes · ⚠️ partial or with caveats (see per-library notes) · ❌ no

The ⚠️ cells specifically: noctud's runtime type checks only apply to stringMapOf/intMapOf. Doctrine's change tracking only fires when wired into the ORM. Illuminate keeps index gaps after filter until you call ->values().

A note on the doctrine row: 3.x is the default branch and requires PHP 8.4. Generics propagation is genuinely full on the modern API (map, filter, partition, findFirst, reduce all carry types through), with slice() as the one exception that drops back to a plain array. If you're stuck on doctrine 2.x for ORM compatibility reasons, the propagation story is weaker.

doctrine/collections

Around since the Doctrine 2 days, present as a transitive dependency in a huge chunk of PHP code on Packagist. The API is what you'd expect:

use Doctrine\Common\Collections\ArrayCollection;

$users = new ArrayCollection([$user1, $user2, $user3]);
$active = $users->filter(fn($u) => $u->isActive());
$first = $active->first();
$count = $active->count();

The thing nothing else here can replicate is the ORM tie-in. When you reassign $user->tags = new ArrayCollection([...]), Doctrine knows what was added and removed and writes the SQL to sync. Invisible if you're not using Doctrine, but it's why this library exists.

Outside that use case, the limits show up fast. Single Collection type, no Set/List/Map split. No immutable variant. No real Map with arbitrary keys (keys are constrained to array-key, same as PHP arrays). The generics story on the 3.x branch is actually solid; map/filter/partition carry types through cleanly, with slice() as the one method that drops back to a plain array.

The other rough edge is the false-on-failure pattern. first() and last() return T|false instead of T|null, so they don't compose with ??. findFirst() returns T|null (correct). The inconsistency within the same interface is annoying, and the false sentinel collides with collections that legitimately hold booleans. A coherent design has first() throw on empty and firstOrNull() return null for ?? chains; doctrine doesn't split it that way.

If you're using Doctrine ORM, this is the answer and you already have it. If you're not, the rest of this post is more useful to you.

illuminate/collections

If you've written Laravel, you've used Collection. It's effectively the standard utility library for PHP at this point. Filter, map, groupBy, partition, pluck, where, sortBy, take, plus 130-something more, all chainable.

use Illuminate\Support\Collection;

$users = collect([$user1, $user2, $user3]);
$active = $users
    ->filter(fn($u) => $u->isActive())
    ->sortBy('createdAt')
    ->take(10);

The good parts are real. Method chaining is smooth, the API surface is enormous, the docs are excellent, every Laravel package speaks Collection, and PhpStorm with Laravel Idea has solid inference. There's also a LazyCollection for streaming over big datasets without loading the whole thing into memory.

The structural limits are also real. Single Collection type, so the shape critique applies here directly. Underneath, a Collection is array<mixed, mixed>. The generic annotations (Collection<TKey, TValue>) exist but PHPStan doesn't reliably propagate them through long chains. There's no real Set, you call ->unique(). No real Map either; if you want non-string keys you're back to fighting PHP. No immutable variant; some methods return new instances, others mutate the original, and the type system doesn't tell you which is which. Filtering leaves index gaps until you remember to call ->values().

There's also the column-oriented magic to grapple with. pluck('name'), where('active', true), keyBy('id'), sortBy('created_at'), groupBy('category'): these all assume your items are arrays or objects with named columns, and they reach inside the items via string keys to read those columns. Powerful for the database-row case Laravel was built around. Awkward outside it, and the type system can't help you here; rename a property and all the where('oldName', ...) calls keep compiling and silently break. It's the kind of API surface that makes Collection feel like a query builder for in-memory rows rather than a generic data structure.

If you're in a Laravel project, this is the right answer. The framework includes it, the ecosystem speaks it, fighting that is a waste of energy. Outside Laravel, the dependency footprint is heavier than it should be and you're paying for an ecosystem you're not using.

loophp/collection

Pol Dellaiera's collection library, built around lazy evaluation via PHP generators. The fluent API has roughly the surface area of Laravel's collections, but every operation defers until you actually consume the chain.

use loophp\collection\Collection;

$active = Collection::fromIterable($users)
    ->map(fn($u) => $u->refresh())
    ->filter(fn($u) => $u->isActive() && $u->isAdmin())
    ->all();

The lazy-by-default model is the win here. Long chains of transformations don't materialize intermediate arrays; you get one walk through the data with all operations composed. For streaming inputs (file lines, paginated query results, anything where you don't want the whole thing in memory at once), this is the right model.

Static analysis is a focus, the codebase is well-typed, and PHPStan can follow the chain types better than most. The library is actively maintained with a thoughtful design.

The trade-offs are the usual lazy-evaluation ones: debugging is harder (the chain doesn't run until you ask for results), some operations require materialization implicitly, and the mental model is less friendly to people who haven't worked with generators or FP languages. It's also a single Collection type, so the shape critique applies; no separate Set/List/Map.

If your code is heavy on data pipelines and the eager/lazy distinction is something you want to control explicitly, loophp/collection is a strong choice. For mostly-small in-memory collections, the lazy machinery is overhead you don't need.

Note on DusanKasan/Knapsack, in case you've seen it mentioned in older PHP collection comparisons: it covers similar Clojure-shaped lazy territory but the last release was in 2017. It's effectively abandoned and shouldn't be picked for new work today.

noctud/collection

I built this one. PHP 8.4+, takes the Kotlin and C# collection designs and adapts them to what PHP 8.4 can actually do well.

use function Noctud\Collection\listOf;
use function Noctud\Collection\mutableMapOf;

$users = listOf($userArray);
$active = $users
    ->map(fn(User $u) => $u->refresh())
    ->filter(fn(User $u) => $u->isActive());

$user = new User('alice');
$roles = mutableMapOf();
$roles[$user] = 'admin'; // object as key, no Fatal error

A few things that don't show up in the others:

Mutable and immutable are separate types (MutableList<T> vs ImmutableList<T> etc.). Immutable mutations are annotated with #[NoDiscard], which becomes a real warning in PHP 8.5 if you forget to capture the result. Combined with the real List/Set/Map split (see the shape section above), the type system carries a lot more information than in the array-wrapper libraries.

Generics actually propagate. PHPStan level 9 clean across the codebase, and the types reach into your code so you're not narrowing mixed returns to assert.

Maps preserve key types. '1' stays a string, true stays a bool, objects work as keys via spl_object_id or your own Hashable implementation. There are also stringMapOf() and intMapOf() variants if you want a single key type enforced at construction.

$map->keys, $map->values, and $map->entries are real Set and List instances backed by the same store. Not arrays, not copies. Full collection API on each:

$map = mapOf(['a' => 1, 'b' => 2, 'c' => 3]);

$map->keys; // ImmutableSet {'a', 'b', 'c'}
$map->keys->first(); // 'a'
$map->keys->sorted()->joinToString(', '); // 'a, b, c'

$map->values->sum(); // 6
$map->values->any(fn($v) => $v > 2); // true

$map->entries->first(); // MapEntry('a', 1)

In ramsey, doctrine, illuminate, and loophp, $map->keys() (or equivalent) is a plain PHP array and you'd be wrapping it back into a collection by hand to chain anything.

Lazy initialization uses PHP 8.4's actual lazy-objects feature, not a wrapper class. Pass a closure to any factory and materialization waits until you read.

Indices shift correctly on removal from indexed lists, which solves the ramsey #133 case.

What's not great about it: PHP 8.4+ only, so if you're on 8.2 or 8.3 you can't use it. v0.1.1 right now, so it hasn't seen the production hours that doctrine and illuminate have. No third-party plugins beyond the official PhpStorm one, no Stack Overflow corpus to search; you'll be reading the docs and the source. I maintain it solo on two days a week, so feature work moves slower than at the bigger libraries.

If you're on PHP 8.4+ and want the best static-analysis story available, plus immutability, key preservation, and change tracking, it's the right answer. If not, one of the others probably fits better.

ramsey/collection

Focused, framework-agnostic, built around runtime type enforcement. Has separate Set, List, and Map types rather than a single Collection class, which puts it on the same architectural side as noctud. The constructor takes a type string and the collection rejects anything that doesn't match.

use Ramsey\Collection\Collection;

$users = new Collection(User::class);
$users->add($user); // OK
$users->add('string'); // InvalidArgumentException

There's also Set, Map, Queue, Stack, and a few specialized variants. PHPDoc generics are well-developed; Collection<int, User> propagates through most operations.

The thing that bites people eventually is issue #133: when you remove an element from an indexed collection, the remaining indices don't shift down.

$col = new Collection('string', ['a', 'b', 'c']);
$col->remove($col[1]); // [0 => 'a', 2 => 'c']

You can call array_values($col->toArray()) and re-wrap, but at that point you're working around the library, not with it. Issue's been open since 2020.

The API surface is intentionally minimal, and that's where it shows. MapInterface has 10 methods. Sub-collections don't compose: $map->keys() returns a plain list<K>, not a Set<K>. There's no values() or entries() method on the Map interface; values come out only via toArray() from the parent. Keys are constrained to PHP's array-key (int or string), so no object keys, no preserved bool/float/numeric-string keys. The type-enforcement story is good. The type-composition story stops at the first hop. If you want to chain $map->keys->filter(...)->sorted() the way Java or Kotlin let you, you're going to wrap arrays back into collections by hand a lot.

No immutable variant either, and runtime checks have a measurable cost on hot paths.

If you want runtime type enforcement, framework-free, on a project that's not on PHP 8.4 yet, this is still your library. The runtime checks earn their keep when you're consuming data from sources you don't fully trust. Just go in expecting a thin layer rather than a full collections framework.

Picking one

Already on Doctrine ORM: doctrine/collections, no contest.
Laravel project: illuminate/collections, don't fight the framework.
Heavy data pipelines, lazy-by-default ergonomics, framework-free: loophp/collection.
Framework-free, PHP 8.1 to 8.3, want runtime type checks: ramsey/collection. Expect a minimal API surface (sub-collections don't compose) and #133 for indexed removals.
Framework-free, PHP 8.4+, prioritize static analysis and the real Set/List/Map split: noctud/collection.

These libraries don't really compete the way the framing of this post implies. Each one solved a specific problem for the people who built it. Doctrine needed an ORM-aware collection layer. Laravel needed a fluent utility class. loophp wanted Clojure-style lazy pipelines. Ramsey wanted type-safe collections without a framework dependency. I wanted a PHP 8.4-shaped library with real Set/List/Map separation that wasn't there.

The shape question is the one I'd think about first. If your code lives mostly in the array-wrapper world (Laravel, Doctrine, FP pipelines), the single-Collection libraries fit naturally. If you keep finding yourself wanting a Set that enforces uniqueness or a Map that respects key types, you're going to want one of the libraries that takes those distinctions seriously, and there are exactly two: ramsey/collection (PHP 8.1+, runtime checks) and noctud/collection (PHP 8.4+, static-analysis-first).

If you're starting a greenfield PHP 8.4+ project today and your default is to install whatever you used last time out of habit, look around first. The right collection library saves you a lot of array_values(array_filter(...)) over the lifetime of a codebase.

Read more:

Type-safe collections in PHP 8.4: what I wish arrays had

delacry — Sat, 25 Apr 2026 19:07:42 +0000

You know the feeling. You're three callbacks deep in array_map, you tack on array_filter, then array_values to fix the keys, and PhpStorm gives up and types everything as array. PHPStan was useful five lines ago. Now it's just nodding politely.

I spent six months of weekends building a library to fix this. It's called noctud/collection, it's PHP 8.4+ only, and this post is about why.

The everyday pain

Here's a scene that probably looks familiar:

$activeAdmins = array_values(
    array_filter(
        array_map(fn($u) => $u->refresh(), $users),
        fn($u) => $u->isActive() && $u->isAdmin()
    )
);

Three problems packed into one expression.

Read order fights execution order. Your eyes hit array_values first, but it runs last. You parse the code in the opposite direction it executes, every time, forever.

Types collapse. array_filter returns array<int, User>. array_values returns array<int, User>. Try the same thing with a User|Customer union and a couple of generic helpers in the chain, and PHPStan starts shrugging.

The array_values is there to plug a hole in PHP itself. Filtering leaves index gaps. You forget the call once and your JSON output suddenly serializes as an object instead of an array because your indices went 0, 2, 5.

And then there are keys. PHP arrays don't really have keys, they have a sad approximation of them:

$a = ['1' => 'a'];
var_dump(array_keys($a)); // [0 => int(1)] - your "1" is now an int

$b = [true => 'x', 1 => 'y'];
count($b); // 1 - true and 1 collide

$c = [];
$c[$someUser] = 'admin'; // Fatal error: Illegal offset type

You can't type-annotate these problems away. array<string, User> is a comfortable lie. PHP will happily put int keys in there and PHPStan can only believe whatever you wrote in the docblock.

What I built instead

Three real types: List, Set, Map. Each one in mutable, immutable, and lazy flavors. Full generics that flow through every method. Implementations are hidden behind interfaces, so swapping internals later is free.

Here's the same code, rewritten:

$activeAdmins = listOf($users)
    ->map(fn(User $u) => $u->refresh())
    ->filter(fn(User $u) => $u->isActive() && $u->isAdmin());

That's the whole thing. Top to bottom in reading order, no plumbing call to fix indices, and PHPStan keeps ImmutableList<User> all the way through. If map() had narrowed the element type, you'd get that propagated too.

Maps stop lying about keys.

Objects work, no Fatal error:

$user = new User('Jesse');
$roles = mutableMapOf();
$roles[$user] = 'admin';
$roles[$user]; // 'admin'

Default object hashing uses spl_object_id. Implement Hashable on your own classes when you want value-based identity instead of reference identity, which is what you usually want for value objects.

For mixed key types, you can't go through an array literal at all (PHP casts at the literal level, before any function sees it). mapOfPairs sidesteps that by taking pairs:

$flags = mapOfPairs([
    [true, 'enabled'],
    [1, 'one'],
    ['1', 'string-one'],
]);
$flags->count(); // 3 - PHP arrays would have collapsed all three

When you specifically want a Map<string, V> and you're getting data from somewhere PHP has already mangled (a request, a DB row, a JSON decode), stringMapOf() is the recovery path:

$config = stringMapOf(['1' => 'enabled']);
$config->keys; // ImmutableSet {'1'} - cast back to string at construction

There's a matching intMapOf() that goes the other direction and rejects anything that isn't an int. The factories enforce the key type at construction, so the analyzer and the runtime end up agreeing on array<string, V> (or array<int, V>) without you having to lie in a docblock.

Things you probably don't get from other libs

Mutable and immutable are separate types, not flags.
MutableList<T>::add() returns $this. ImmutableList<T>::add() returns a new instance and is annotated with #[NoDiscard], which becomes a real warning in PHP 8.5. No more silently throwing your "added" element into the void.

Map views are live collections.
$map->keys, $map->values, and $map->entries are real Set and List instances backed by the same underlying store. They share memory and they have the full collection API. So $map->values->sum() and $map->keys->sorted() just work, no copying.

Change tracking, only when you actually want it.

$tags = mutableSetOf(['php', 'kotlin']);
$result = $tags->tracked()->add('php');
$result->changed; // false - 'php' was already in the set

I wrote this for cache invalidation logic and got tired of writing the "did this actually do anything" check by hand.

Lazy initialization via PHP 8.4 lazy objects.
Pass a closure to any factory and the data is materialized only when first accessed. Copy-on-write between mutable and immutable variants is virtually free for the common case where you don't mutate after converting.

A small PhpStorm plugin that fixes a couple of generic-inference quirks the IDE has with callbacks and __invoke. A few of the bugs I reported upstream while I was at it.

Where the design comes from

If the API feels familiar after using Kotlin or modern C#, that's intentional. Kotlin got the mutable/immutable split right, the read-only interfaces right, and the chained pipeline ergonomics right. Java laid down the foundational List/Set/Map vocabulary decades earlier. I borrowed from both, the FAQ walks through the specific differences if you want them.

PHPStan level 9 and Psalm strict, both clean. The generics carry through into your code, so your call chains stay typed end to end with no mixed returns to narrow.

Try it

composer require noctud/collection

The default pin (^0.1.1) keeps you on 0.1.x patches only. BC breaks ship as 0.2 and composer won't auto-install them, so locking this way is safe through the 0.x cycle.

Docs and examples: https://noctud.dev
GitHub: https://github.com/noctud/collection

I'm planning a few 0.x releases through 2026 before locking the API for 1.0. Big remaining work is a Sequence type for lazy intermediate operations (similar to Kotlin sequences or Java streams), and a tests refactor.

If you try it on something real and the API gets in your way, I want to hear about it. Right now is when feedback actually shapes 1.0.