PhpStorm warns about "Expected class1, got class2" when class2 extends class1 - php

Question

I'm using Phalcon Framework and it has class for models: Phalcon\Mvc\Model (from now only as P\M\Model). I've defined base domain, which extends that class and then every other domain extends my base domain, thus Phalcons Model class:
Domain.php:
class Domain extends \Phalcon\Mvc\Model
{
...
}
DomainA.php:
class DomainA extends Domain
{
...
}
then I'm using repository manager to get repository for DomainA models. All repositories have same parent, similarly as Domain, which has defined method find()
Repository.php:
class Repository
{
/**
* Will always return object of classes
* which extends Phalcon\Mvc\Model
*
* #return Phalcon\Mvc\Model
*/
public function find()
{
...
$domain::find();
}
}
RepositoryA.php:
class RepositoryA extends Repository
{
...
}
So, the RepositoryA now has method find() from its parent and because parent does not know exactly what he is going to return, but knows parent of what all the returns are so it is type-hinting it via #return.
Then I have some other class, which has method expecting only DomainA object, which is also parent of P\M\Model and I try to push there object of that type it works OK, because returned object from repository actualy IS an DomainA object, but Repository annotates it as P\M\Model so PhpStorm highlights it with message "Expected DomainA, got Phalcon\Mvc\Model..."
public function pleaseGiveDomainA(DomainA $obj)
{
...
}
// Works OK but is higlighted in IDE
$this->pleaseGiveDomainA($repositoryA->find());
How should I annotate this kind of stuff? Hinting in #return all cases of domains like #return DomainA|DomainB|DomainC... is no good as we have hundreds of Domains, also expecting in function the parent P\M\Model is no good, because we want to be sure its only DomainA.
Thanks.

Answer 1

try using an interface rather than a base model. In my experience sometimes PHPStorm can get confused with this sort of complex class hierarchy. In my programs I define an interface and type hint against that. Which allows PHPStorm to properly detect the class

Answer 2

If you redefine find() in class RepositoryA then just annotate its implementation with #return DomainA. Otherwise, declare find() as #method in the docblock of class RepositoryA with DomainA as its return type.
Both approaches are displayed below:
/**
* #method DomainA find() <-- use this when the method is inherited
* but not redefined in this class
*/
class RepositoryA extends Repository
{
/**
* #return DomainA <-- preferably use this
*/
public function find()
{
}
}
A similar trick can be used for inherited properties that in the children class store objects of classes that extend the class used in annotation in the base class:
/**
* #property DomainA $member <-- it was declared as #var Domain $member
* in the base class
*/

Answer 3

PSR-5 defines a #method tag.
Syntax
#method [return type] [name]([type] [parameter], [...]) [description]
Examples
/**
* #method string getString()
* #method void setInteger(int $integer)
* #method setString(int $integer)
*/
class Child extends Parent
{
<...>
}
abstract class EntitySerializer {
/**
* #return Entity
*/
abstract public function getEntity();
}
/**
* #method RealEntity getEntity()
*/
abstract class RealEntitySerializer extends EntitySerializer {}
/**
* #method PseudoEntity getEntity()
*/
abstract class PseudoEntitySerializer extends EntitySerializer {}
Re: taken from my SO answer here.