php / phpDoc - @return $this 类的实例？

Question

如何在 phpDoc 中将方法标记为“返回当前类的实例”？

在下面的示例中，我的 IDE (Netbeans) 将看到 setSomething 始终返回一个 foo 对象。

但如果我扩展对象，情况就不是这样了 - 它会返回 $this，在第二个示例中它是一个 bar 对象，而不是 foo目的。

class foo {
    protected $_value = null;

    /**
     * Set something
     *
     * @param string $value the value
     * @return foo
     */
    public function setSomething($value) {
        $this->_value = $value;
        return $this;
    }
} 

$foo = new foo();
$out = $foo->setSomething();

很好 - setSomething 返回一个 foo - 但在下面的示例中，它返回一个 bar..:

class bar extends foo {
    public function someOtherMethod(){}
}

$bar = new bar();
$out = $bar->setSomething();
$out->someOtherMethod(); // <-- Here, Netbeans will think $out
                         // is a foo, so doesn't see this other
                         // method in $out's code-completion

... 那就太好了对于我来说，为了解决这个问题，代码完成是一个巨大的速度提升。

有人有一个聪明的技巧，或者更好的，一个用 phpDoc 记录这个的正确方法吗？

Answer 1

更新：

从 Netbeans 7.4 开始，IDE 支持 @return self、static 和 this (http://wiki. netbeans.org/NewAndNoteworthyNB74#Editor_2）。

class foo {
    protected $_value = null;

    /**
     * Set something
     *
     * @param string $value the value
     * @return this
     */
    public function setSomething($value) {
        $this->_value = $value;
        return $this;
    }
}

class bar extends foo {
    public function someOtherMethod(){}
}

---

上一个答案：

我们对记录迭代器的 current() 方法也有类似的问题。由于迭代器针对许多不同的类进行了扩展，因此与它关联的 @return $class 是没有意义的。我们之前使用过@satrun77的选项2，但我使用过 @method 在 Netbeans 中取得了一些成功。

class foo {
    protected $_value = null;

    /**
     * Set something
     *
     * @param string $value the value
     * @return foo
     */
    public function setSomething($value) {
        $this->_value = $value;
        return $this;
    }
}

/**
 * @method bar setSomething($value)
 */
class bar extends foo {
    public function someOtherMethod(){}
}

Answer 2

当我遇到一些事情时，我想我会重新审视这个问题。

目前不支持“return $this”，但有一个 PhpDoc 请求在 v1.5 中添加这一点：

http://pear.php.net/bugs/bug.php?id=16223

Eclipse PDT 中也有一个请求：

https://bugs.eclipse.org/bugs/show_bug.cgi?id=276082

两者都是相对较旧的请求。我不会对很快实现这一点感到太兴奋，但这里希望:)与此同时，似乎这个问题没有适当的解决方案。

Answer 3

！解决了！ - 升级到netbeans 9.0（截至2018年7月稳定？）

我已经追求这个一年多了，终于有了一个开源解决方案！ :)

class Input extends BasicHtml
{    
    public function someOnlyInputFunc()
    {

    }
}

class Table extends BasicHtml
{
    public function tableOnlyFunc()
    {

    }
}

abstract class BasicHtml
{

    /**
     * 
     * @param array $arrayForNow
     * @return $this
     */
    public function setStyle( array $arrayForNow )
    {        
        return $this;
    }
}


/////driver
$table = new Table();
$input = new Input();
$input->setStyle(array())->//now shows only Input + baseHtml functions
$table->setStyle(array())-> //now shows only Table + baseHtml functions
///note - in 8.0.2 version it shows blank obj drop downs on exact same code.

这也适用于特征。截至 2018 年 11 月 1 日，9.0 以大 zip 形式提供（没有适用于 Windows、Mac 的全新安装程序？），您将不得不搜索添加 php 插件等，但它确实有效！我花了大约一个小时才把它全部设置好。我还安装了旧的 8.x，并与新的 9.0 一起运行，没有任何问题......到目前为止（只是不要同时运行它们）。插件提示： https://www.reddit.com/r/PHP/评论/9gtaaw/how_to_run_netbeans_9_with_php_support/

Answer 4

这里有 3 个解决方法：
（这些只是解决方法。不得设计和实现类来影响 IDE 的行为）

选项 1：
将 foo 类中的方法 someOtherMethod 设为抽象或空方法

class foo implements ifoo {
    protected $_value = null;

    /**
     * Set something
     *
     * @param string $value the value
     * @return ifoo
     */
    public function setSomething($value) {
        $this->_value = $value;
        return $this;
    }

    // abstract method or create empty method if you want the method to be
    // to be optional 
    abstract function someOtherMethod();
}

选项 2：

覆盖 bar 类中的方法 setSomething

class bar extends foo {
    /**
     *
     * @param <type> $value
     * @return bar
     */
    public function setSomething($value) {
        return parent::setSomething($value); 
    }

    public function someOtherMethod(){}
}

选项 3：
使用界面

interface ifoo {
    public function someOtherMethod(){}
}

class foo {
    protected $_value = null;

    /**
     * Set something
     *
     * @param string $value the value
     * @return ifoo
     */
    public function setSomething($value) {
        $this->_value = $value;
        return $this;
    }
}

class bar extends foo implements ifoo {

    public function someOtherMethod(){}
}

Answer 5

phpDoc 语法允许通过用 < 分隔来定义多种类型@return 标记 的 code>| 字符。当您使用 class bar 扩展 class foo 时，您应该编写一个新的 phpDoc 标记，该标记具有适合其 @return 的类。

如果函数返回 foo 或 bar，那么您将使用 @return foo|bar。

但是，在您的情况下，只需为覆盖的函数定义 @return bar 即可。

小心。