Allow narrowing of type in PHPDoc

[Jean85]

Take this code as an example

<?php declare(strict_types = 1);

interface Animal
{}

class Bird implements Animal
{}

abstract class AnimalCage
{
    /** @var Animal[] */
    private $animals;

    /**
     * @return Animal[]
     */
    public function getAnimals(): array
    {
        return $this->animals;
    }

    /**
     * @return Bird[]
     */
    public function getBirds(): array
    {
        return array_filter($this->getAnimals(), function ($val) {
            return $val instanceof Bird;
        });
    }
}

The PHPDoc over getBirds() is marked as an error by PHPStan, because it's somehow expecting @return Animal:

 ------ ---------------------------------------------------------------- 
  Line   analyzed.php                                                    
 ------ ---------------------------------------------------------------- 
  27     Method AnimalCage::getBirds() should return Bird[] but returns  
         Animal[].                                                       
 ------ ---------------------------------------------------------------- 

I would like to restrict the type and not be forced to use the @return Animal[] | Bird[] workaround to avoid errors with PHPStan.

[JanTvrdik]

@Jean85 I have trouble understanding your problem. Can you reproduce it on https://phpstan.org/?

[Jean85]

Sorry, I had wrongly narrowed down my problem. I've edited my starting example with something that now gets you the error that I wanted to report.

[ondrejmirtes]

The problem is here:

        return array_filter($this->getAnimals(), function ($val) {
            return $val instanceof Bird;
        });

Because array_filter return type is inferred from $this->getAnimals() and thats Animal[]. This is quite advanced code to be recognized and understood by PHPStan automatically, so I recommend you to store the result of array_filter into a variable, mark it with @var Bird[] and return that variable.

[ondrejmirtes]

And about the original form of your question (which I retrieved from my email inbox):

interface AnimalCage
{
    public function getAnimal(): Animal;
}

class BirdCage implements AnimalCage
{
    /**
     * @return Bird
     */
    public function getAnimal(): Animal
    {
        // ...
    }
}

This is already supported and in case of Calling BirdCage::getAnimal(), PHPStan will assume that the return type is Bird, thanks to the fact that Bird implements Animal.

[JanTvrdik]

@Jean85 Or use foreach with if. It's a lot faster and a lot easier to statically analyse https://phpstan.org/r/6ef813feadeb02536965559f5d1e59d7

[JanTvrdik]

@Jean85 Turn's out that supporting the array_filter with single return statement in Closure is not that hard. I have a working implementation based on #476, so stay tuned for next version.

[Jean85]

Yeah great! Thanks @JanTvrdik

@ondrejmirtes I imagined that the issue whas somethat there while re-writing the example, thanks.

[ondrejmirtes]

@JanTvrdik #476 got merged, can you send your PR for array_filter Thanks :)

[JanTvrdik]

@ondrejmirtes #561

[ondrejmirtes]

Done, PR merged. Thanks to all!