Perfect! :)

One more idea - these rules should be more loose for immutable classes. PHPStan supports @immutable above classes and also readonly class keyword for PHP 8.2. So I think it's fine to use covariant @param T in a class that's readonly/immutable.

I think there's already a similar exception for constructor.

So I think it's fine to use covariant @param T in a class that's readonly/immutable.

I can see where the idea is coming from, but I have to disagree. This is not about mutability, it's about substitutability.

When I think about generic variance, I do this mental exercise where I "compile" the generics in my head into monomorphized code: a separate class for each instance of the type argument, with the type argument inlined. It really helps me think about the problem in a more hands-on, focused way.

interface Animal {}
interface Dog extends Animal {}

/** @template T */
readonly class Collection
{
    /**
     * @param T $item
     * @return Collection<T>
     */
    public function add($item): self { /* ... */ }
}

I turn the code above into:

readonly class CollectionAnimal
{
    public function add(Animal $item): self { /* ... */ }
}

readonly class CollectionDog
{
    public function add(Dog $item): self { /* ... */ }
}

Now, when I make the template type variant, I'm essentially just adding a subtyping relation between the classes. For a covariant template, I'm saying that readonly class CollectionDog extends CollectionAnimal (and the other way around for a contravariant template):

readonly class CollectionAnimal
{
    public function add(Animal $item): self { /* ... */ }
}

readonly class CollectionDog extends CollectionAnimal
{
    public function add(Dog $item): self { /* ... */ }
}

This obviously violates LSP: wherever I accept CollectionAnimal, I should be able to substitute it with CollectionDog, but that's not possible because I wouldn't be able to add a Cat into it at runtime, readonly or not.

I think there's already a similar exception for constructor.

As I understand it, that's a slightly different case. Private members are ignored altogether while in the constructor, the check just omits the initial positional variance. For covariant T:

/**
 * @param T $a
 * @param callable(T): void $b
 */
public function __construct(
    mixed $a,
    callable $b,
) {}

Here, $a is allowed as a parameter, but $b is not, because it contains the template type in a callable parameter which is a contravariant position.

OK, great, makes sense, thank you :)