PHPDoc:记录始终产生自身或后代类的父类方法？

Question

考虑这段代码:

class ParentClass {

    public static function generate($className = __CLASS__){
        if(!$className) return new self();
        else return new $className();
    }
}

class ChildClass extends ParentClass {

    /**
     * @param string $className
     * @return ChildClass
     */
    public static function generate($className = __CLASS__) {
        return parent::generate($className);
    }
}

var_dump($ChildClass::generate()); // object(ChildClass)[1]

ChildClass::generate() 返回一个 ChildClass 实例，因为我从不提供 $className 参数。问题是我的 IDE 警告我 parent::generate() 调用与记录的返回类型不匹配:

我想通过向父方法添加文档来消除此警告。我可以这样做:

@return ParentClass | ChildClass

将它添加到父方法中是可行的，但这并不实际，因为有许多子类，而且将来可能会有更多。我已经尝试了以下两种方法:

@return static
@return $className

但这并没有使警告消失。是否有 PHPDoc 批准的方法来指示将始终返回调用子类？或者——更准确地说——将返回类型为$className 的类？如果没有，有没有一种方法可以只使用我的 IDE？ (PhpStorm 2017.2)

更新

@gogaz 下面的评论让我想到:如果 PHPDoc @return 可以指示类似 self | 的东西就足够了后代

Answer 1

您可以记录父类方法，然后在子类方法上继承它。

class ParentClass
{
    /**
     * @param string $className
     * @return ChildClass
     */
    public static function generate($className = __CLASS__){
        if(!$className) return new self();
        else return new $className();
    }
}

class ChildClass extends ParentClass
{
    /**
     * @inheritdoc
     */
    public static function generate($className = __CLASS__) {
        return parent::generate($className);
    }
}

希望这能解决您的问题。

更新: 另一种方法是使用所有类都将实现的接口(interface)，因此您可以期望生成方法将返回某个实现该接口(interface)的类。

 /**
  * ...
  * @return MyCustomInterface
  */

如果这不能解决您的问题...那么，您可以将返回类型设置为“混合”，这将抑制警告并且不会说谎 :) 因为您的生成方法可以返回您通过参数指定的任何类...

 /**
  * ...
  * @return mixed
  */