@method annotation type overriding

[HEKET313]

Summary of a problem

@method annotation does not override return type of parent method.

Code snippet that reproduces the problem

I have abstract class which implements \Iterator interface and realizes method current

abstract class PayloadCollectionEvent implements \Iterator {
    // Some inner collection which also implements \Iterator
    protected $items;

    // Other \Iterator methods

    /**
     * @inheritdoc
     * @return PayloadInterface
     */
    public function current()
    {
        return $this->items->current();
    }
}

Also I have child class that have annotation @method which override reutrn type of method current()

/**
 * @method ProductUpdateResponse current()
 */
class ProductBatchUpdateResponseEvent extends PayloadCollectionEvent
{
}

PHPStorm understands that now in foreach loop item has type ProductUpdateResponse (which implements PayloadInterface) not PayloadInterface but PHPStan still recognizes it as PayloadInterface

Expected output

I expect that PHPStan will recognize that this method should return new type.

[ondrejmirtes]

This is weird - @method overriding like this has been working for several versions so there's probably something very special about your use-case.

And indeed it is. The overriding works well for normally called methods, but you're talking about current() and type inferring in foreach construct. Unfortunately, this isn't easy to fix, because ObjectType:: getIterableValueType() reads only native signatures and for a good reason: It does not make much sense to look into method extensions because current() or getIterator() defined using __call would not be used in a foreach. Unfortunately, this eliminates the possibility to read overriden return types from a @method annotation.

To remedy this, I recommend you to define method ProductBatchUpdateResponseEvent::current() that just returns parent::current() and has the correct return typehint, native one or using @return (that would work too).

I have no plans to fix this right now, because it's a huge edge case and it would complicate things. Thanks.