add stub for LimitIterator

[Khartir]

[staabm]

after this PR has been merged, you might have fun adding even more Iterators (one by one with a separate PR)

see https://github.com/phpstan/phpstan-src/pull/1009 for inspiration

note https://github.com/phpstan/phpstan-src/pull/1009#issuecomment-1075160461 though

[Khartir]

We should be compatible with Psalm's stub

I looked into this and as far as I can tell, yes there needs to be a discussion. Both Psalm and PHPStan define IteratorIterator with 3 @template. However Psalm then only has two @template for all extensions of IteratorIterator. As far as I can tell this is not possible in PHPStan. For this reason, there are already some differences: FilterIterator, CallbackFilterIterator and RecursiveCallbackFilterIterator are all defined with 3 @template in PHPStan, while they have only two in Psalm.

Furthermore, as @staabm pointed out, OuterIterator should probably be changed to also have 3 @template, so that the type of getInnerIterator is correct:

/**
 * @template-covariant TKey
 * @template-covariant TValue
 * @template TIterator as Iterator<TKey, TValue>
 *
 * @template-extends Iterator<TKey, TValue>
 */
interface OuterIterator extends Iterator {
    /**
     * @return TIterator
     */
    public function getInnerIterator();
}

This is also missing in Psalm.

[Khartir]

On further testing I realized that changing OuterIterator leads to similar issues as discussed in https://github.com/phpstan/phpstan/issues/6829, because it assumes that the Iterator returned from getInnerIterator is the same as the one passed to the constructor in IteratorIterator (and RecursiveIteratorIterator which is currently missing implements OuterIterator). This wouldn't even work, because both constructors accept Traversable, not Iterator.

[ondrejmirtes]

Hi, I'm cleaning up old and stale PRs. Please send a new PR if you're still interested, thanks.