PHPDoc 用于子类中的流畅接口？答案

【问题标题】：PHPDoc for fluent interface in subclass?PHPDoc 用于子类中的流畅接口？
【发布时间】：2012-11-26 10:47:08
【问题描述】：

有什么理由让我的 IDE（实际上是 PHPStorm）明白这一点：

$student->setName('Marco');

将返回Student 的实例，而不在子类中重新定义setName()（仅用于添加PHPDoc cmets）？

class Person
{
    private $name;

    /**
     * @param string $name
     * @return Person
     */
    public function setName($name)
    {
        $this->name = $name;

        return $this;
    }
}

class Student extends Person { }

【问题讨论】：

仅供参考：上面的“功能”应该是“功能”。我试图将其作为编辑提交，但同行评审拒绝了它并说我应该将其添加为评论。

标签： php phpdoc

【解决方案1】：

您可以在文档块中返回 $this 而不是 person

【讨论】：

【解决方案2】：

你必须像这样覆盖你的方法标签作为评论

/**
 * @method Student setName($name)
 */
class Student extends Person { }

【讨论】：

好吧，这似乎可行，但对许多二传手来说会很痛苦。
您在 Student 中是否有想要通过流利的 Person 方法返回的对象访问的公共方法？如果没有，并且您真的只需要能够看到 Person 的所有方法，那么希望您的 IDE 已经能够显示它们。但是，如果您在 Student 中确实有尚未在 Person 中定义的公共方法，那么也许为了您的 API 的缘故，您可以在 Person 中将它们声明为抽象的。像这样，它们位于 Person API（由 Student 继承）上，仅记录在 Person 中，并且如果 fluent 方法都显示 @return Person，仍然对 IDE 可见。
参数列表不是必须的

【解决方案3】：

根据我的经验，我发现使用组合方法很有帮助。我的 IDE（带有 PHP 插件的 IntelliJ IDEA）抱怨说，当稍后将该值用作另一个方法调用的参数时，我的 fluent 方法正在返回 $this。通过将 PHPDoc 注释更改为：

/**
 * @param string $name
 * @return $this|Person
 */

IDE 更快乐，PHPDoc 为用户提供了更多信息。

顺便说一句，通过在 PHPDoc 中说该方法返回 $this，这很好地表明该方法正在实现一个流畅的接口。说它返回Person，虽然在技术上是准确的，但并不一定表示流畅。例如，创建 new Person 对象并返回它的方法也可以使用相同的注解，但不会流畅。

【讨论】：