How to phpdoc implementation of IteratorAggregate

[mvorisek]

see sandpit code: https://phpstan.org/r/5e9d2a38-e4d7-4fe2-b25e-0094a5f70c5d

usecase https://github.com/atk4/data/blob/1fb2c24b2f5308b04a6c6ef412bb03e26fb2d6e1/src/Model.php#L1770

PHPStan shows an error:

Class Model implements generic interface IteratorAggregate but does not specify its types: TKey, TValue

but phpdoc @return iterable<static> on Model::getIterator() method should be enough

[canvural]

You need something like /** @implements \IteratorAggregate<int, mixed> */ above the class. If you implement or extend a generic class you should specify the values.

[mvorisek]

It does not work - https://phpstan.org/r/f462b4b3-ba01-44e1-a68a-b157e9bd8621, it fixes the first error only.

Also, I think the phpdoc for Model::getIterator() method should be enough, is this a bug?

Adding @implements \IteratorAggregate<static> is fine, but the later error must not be shown and static must be correctly resolved.

[ondrejmirtes]

There’s a documentation page describing everything around generics: https://phpstan.org/blog/generics-in-php-using-phpdocs

[mvorisek]

The blogpost does not discuss getIterator method. Phpstan can not assume that IteratorAggregate makes whole class generics.

Here is usecase from a real code: https://github.com/atk4/data/blob/b67712cbf710fcd3605798d80be23cd6904a3c2f/tests/ContainsManyTest.php#L54

Model and all child classes are NOT generics. These classes allow only to be iterated over itself as ORM active record design pattern.

[mvorisek]

@ondrejmirtes please help with this, I strongly belive https://phpstan.org/r/f462b4b3-ba01-44e1-a68a-b157e9bd8621 should work and it is very important for projects like atk4/data where getIterator method is defined on abstract/base class. Thanks in advance!

[ondrejmirtes]

@mvorisek Looks like StaticType isn't expanded in @extends/@implements. This is how it's usually done: https://github.com/phpstan/phpstan-src/blob/842625e8c2f11279bc28bdae1e4466028df46930/src/Analyser/MutatingScope.php#L4571-L4582

A similar thing needs to be done somewhere around here https://github.com/phpstan/phpstan-src/blob/842625e8c2f11279bc28bdae1e4466028df46930/src/Reflection/ClassReflection.php#L186-L201 and here https://github.com/phpstan/phpstan-src/blob/842625e8c2f11279bc28bdae1e4466028df46930/src/Reflection/ClassReflection.php#L594-L599.

As an alternative implementation, you can do this: https://phpstan.org/r/9829582c-f3a5-48e4-ae43-d43d709e8282

[mvorisek]

@ondrejmirtes yes, @extends does not work with static too, test case here https://phpstan.org/r/ac3a84c9-fa97-4852-8149-d36b26d48168 . I do not have the knowledge to fix this, can you please look into it?

[ondrejmirtes]

I opened an issue about this #4267, but fixing it does not align with my current priorities right now, sorry.

A PHPStan bug is rarely a blocker for its users as you can ignore the issue or use a workaround.