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

.4 readonly collections with PHPStan generics eliminates runtime type violations while preserving near-native memory footprint.

• array_is_list() validation at construction time prevents index drift and ensures predictable iteration behavior.
• The sweet spot lies in dual enforcement: static analysis catches 95% of issues at CI time, while lightweight runtime guards catch the remaining 5% during dynamic data ingestion (API payloads, DB results, cache deserialization).

Core Solution

Architecture Decision

• Use readonly classes to enforce immutability and prevent accidental mutation of internal arrays.
• Leverage PHPStan/Psalm generics (@template T) for IDE autocompletion and static analysis.
• Implement runtime type validation using match expressions and array_is_list() for index safety.
• Keep the collection thin: delegate iteration to native PHP array functions where possible to avoid performance penalties.

Implementation Example

<?php

declare(strict_types=1);

namespace App\Collections;

use InvalidArgumentException;
use function array_is_list;
use function array_values;
use function is_array;
use function is_int;
use function is_string;

/**
 * @template T
 */
readonly class TypedCollection
{
    /**
     * @param class-string<T>|null $type
     * @param array<T> $items
     */
    public function __construct(
        private ?string $type = null,
        private array $items = []
    ) {
        if (!array_is_list($this->items)) {
            throw new InvalidArgumentException('Collection must be a sequential list.');
        }

        if ($this->type !== null) {
            $this->validateTypes();
        }
    }

    /**
     * @return array<T>
     */
    public function all(): array
    {
        return $this->items;
    }

    public function count(): int
    {
        return count($this->items);
    }

    /**
     * @param callable(T): bool $predicate
     * @return self<T>
     */
    public function filter(callable $predicate): self
    {
        return new self(
            $this->type,
            array_values(array_filter($this->items, $predicate))
        );
    }

    /**
     * @template U
     * @param callable(T): U $callback
     * @return self<U>
     */
    public function map(callable $callback): self
    {
        return new self(null, array_map($callback, $this->items));
    }

    private function validateTypes(): void
    {
        foreach ($this->items as $index => $item) {
            $expected = $this->type;
            $isValid = match (true) {
                is_string($expected) && class_exists($expected) => $item instanceof $expected,
                $expected === 'int' => is_int($item),
                $expected === 'string' => is_string($item),
                $expected === 'array' => is_array($item),
                default => throw new InvalidArgumentException("Unsupported type: {$expected}")
            };

            if (!$isValid) {
                throw new InvalidArgumentException(
                    sprintf('Item at index %d must be of type %s, %s given.', $index, $expected, get_debug_type($item))
                );
            }
        }
    }
}

Usage Pattern

// Static analysis + runtime safety
$users = new TypedCollection(User::class, [
    new User('alice'),
    new User('bob'),
]);

// IDE knows $user is User
$active = $users->filter(fn(User $user) => $user->isActive());

// PHPStan infers return type correctly
$names = $active->map(fn(User $u) => $u->name);

Pitfall Guide

1. Relying solely on PHPStan/Psalm without runtime guards: Static analysis runs at CI time. Dynamic data (HTTP requests, cache, DB) bypasses it. Always validate at collection construction.
2. Ignoring array_is_list() validation: Associative arrays break iteration contracts and cause off-by-one errors in map/filter chains. Enforce sequential indexing at instantiation.
3. Mutable internal state breaking type contracts: Storing collections in mutable properties allows external code to inject invalid types. Use readonly classes and return new instances on transformation.
4. Overusing instanceof in hot loops: Runtime type checks add overhead. Cache type expectations, validate once at construction, and trust the collection internally after instantiation.
5. Misaligning PHPDoc generics with actual types: @template T without corresponding @param/@return annotations breaks IDE inference. Keep PHPDoc signatures synchronized with method implementations.
6. Forgetting to handle null vs missing keys: PHP arrays treat missing keys as null in loose comparisons. Use strict typing and explicit isset/array_key_exists when extracting values.
7. Not leveraging PHP 8.4 match for type routing: Legacy if/else or switch chains for type validation are verbose and slower. match expressions provide exhaustive, optimized type routing.

Deliverables

• Blueprint: php84-type-safe-collection-architecture.pdf – System design showing static analysis pipeline, runtime validation boundaries, and integration points with Symfony/Laravel service containers.
• Checklist: collection-implementation-checklist.md – Step-by-step validation covering PHPDoc generics, readonly enforcement, array_is_list() guards, PHPStan/Psalm config, and CI gate rules.
• Configuration Templates:
  • phpstan.neon – Generic collection rules, @template enforcement, and array_is_list() usage policies.
  • psalm.xml – Type inference settings, immutable collection annotations, and runtime validation suppression rules.
  • TypedCollectionBase.php – Production-ready skeleton with PHP 8.4 features, ready for domain-specific extension.