Covariant template types in collections

[martin-heralecky]

(see answer below)
I suggest that types of values in collections are declared covariant, so that static analyzers work better with generic types and inheritance.

PhpStan natively treats types of values of arrays (and iterables in general) as covariant, which I think is what people usually expect (iterable<Child> is a subtype of iterable<Parent> when Child extends Parent). This, however, is not true for Laravel's Enumerable, LazyCollection and Collection, because they declare the template type with @template TValue instead of @template-covariant TValue.

Here's an example, for which PhpStan fails:

use Illuminate\Support\Collection;

class FooParent {}

class FooChild extends FooParent {}

interface BarInterface {
    /**
     * @return Collection<int, FooParent>    <-- notice FooParent
     */
    public function bar(): Collection;
}

class BarImpl implements BarInterface {
    public function bar(): Collection {
        return collect([
            0 => new FooChild(),          // <-- notice FooChild
        ]);
    }
}

Method BarImpl::bar() should return Illuminate\Support\Collection<int, FooParent> but returns Illuminate\Support\Collection<int, FooChild>.

If we replace Collection with array, the analysis passes.

Btw, Psalm supports the @template-covariant annotation as well (https://psalm.dev/docs/annotating_code/templated_annotations/#template-covariance).

[Radiergummi]

Ah, that's an annoying one. I wish the static analysis community had opted to do the opposite and make covariant the default behaviour, but that's what we got. I'm creating a PR for this.

[Radiergummi]

Ah, snap. Just discovered this has already been implemented in #49234, but only for Laravel >=10.

[martin-heralecky]

I actually don't think it's a good idea anymore. Covariance makes sense only for read-only collections (see e.g. comments on this SO answer and related article).

Anyway, since it's already been implemented, I guess this can be closed.