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

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.