ArrayIterator TValue is not covariant and fails when passed against IteratorAggregate

[Steveb-p]

I can't really explain this behavior to a colleague, so I figured someone might offer some insight.

We have a piece of code (test, actually) that is supposed to create a dummy Traversable object. We figured we will narrow down the return type (Iterator -> ArrayIterator) and so we also added the annotation indicating that we are interested in array<int> as results.

However, PHPStan reports array{int,int,int,int}|array{int} as incompatible, which raised our eyebrows.

Why does it happen? 🤔

https://phpstan.org/r/673467b9-520d-4290-98c8-9ca5e9d76ef5

<?php declare(strict_types = 1);

class HelloWorld
{
	
    /**
     * @return \Traversable<int, array<int>>
     */
    public function buildTraversableObject(): Traversable
    {
        return new class() implements IteratorAggregate {
			/**
			 * @return \ArrayIterator<int, array<int>>
			 */
            public function getIterator(): \ArrayIterator
            {
                return new ArrayIterator(
                    [
                        [1, 2, 3, 4],
                        [5],
                    ]
                );
            }
        };
    }

	/**
     * @return \Traversable<int, array<int>>
     */
    public function buildTraversableObject2(): Traversable
    {
        return new class() implements IteratorAggregate {
            public function getIterator(): \Iterator
            {
                return new ArrayIterator(
                    [
                        [1, 2, 3, 4],
                        [5],
                    ]
                );
            }
        };
    }
}

Error reported:

Line 17:	
Method class@anonymous/tmp.php:11::getIterator() should return ArrayIterator<int, array<int>> but returns ArrayIterator<int, array{int, int, int, int}|array{int}>.
Template type TValue on class ArrayIterator is not covariant. Learn more: [What's Up With @template-covariant?](https://phpstan.org/blog/whats-up-with-template-covariant)
[return.type](https://phpstan.org/error-identifiers#gbi-return.type)

[ondrejmirtes]

The playground tells you: Template type TValue on class ArrayIterator is not covariant. Learn more: What's Up With @template-covariant?

The article explains that.

You can cast the returned type though: https://phpstan.org/r/c1d8b1db-e5db-4105-bef0-b586943350fa

[Steveb-p]

I roughly understand the @template-covariant and what it means. I was just surprised that changing the return type - like in the second example - caused PHPStan to start reporting incompatibility between types.

I expected that since Iterator<int, array<int>> accepted array{int, int, int, int}|array{int} as TValue, then ArrayIterator<int, array<int>> will also accept the same TValue. That was my expectation. Maybe I don't undestand something abour covariancy here 🤔