我应该使用 @return self，this 还是当前类？

Question

我有一个返回当前对象的方法，如何对其进行文档化？

/**
 * set something
 *
 * @return this
 */
public function setSomething(){
            // ...
    return $this;
}

还是应该使用@return self，还是@return Current_Class_Name？

---

为什么这个问题不是“基于主观看法”的（应该被重新打开）：符合标准和IDE类型提示支持。

- lucaswxp

---

相关内容，针对静态的：https://dev59.com/m2025IYBdhLWcg3wr4F6 - Greg

Answer 1

有一个PHP标准推荐(PSR)，目前处于草案状态，(PSR-5)提出使用@return $this来表示返回的是同一实例。

$this，该类型适用于此元素的实例与当前类在给定上下文中的实例完全相同。因此，此类型是static的更严格版本，除了返回的实例必须是相同的类之外，还必须是相同的实例。

此类型通常作为实现流畅接口设计模式的方法的返回值。

目前，流行的IDE，如PhpStorm和Netbeans都使用了这种表示法。

- g .

---

您的回答含混不清，因为它听起来好像这个PSR建议使用$this。我认为这并不正确。它只是允许它，就像Current_Class_Name和self一样。 - marcv

还要注意，它是 @return $this 而不是 @return this，就像问题所问的那样。 - SOFe

我使用 PHP Storm，而 $this 会使其不稳定，而 self 和 \Class 则不会。 - David Yell

请注意，PSR-5已被废弃。 - AnthonyB

phpstan（PHP静态分析工具）也更喜欢使用@return $this。 - Sven

Answer 2

@return Current_Class_Name 一定可行，这也是我喜欢的方式。

@return self 在某些程序中也可能可行。

@return this 是错误的，因为this不是一个类型名。

- RiaD

---

目前来说，"return Current_Class_Name" 是最好的选择，因为它可以让 IDE 自动完成成功。phpDocumentor [1] 和 Eclipse PDT [2] 都有功能请求，希望能够识别 "return $this"。[1] -- http://pear.php.net/bugs/bug.php?id=16223 [2] -- https://bugs.eclipse.org/bugs/show_bug.cgi?id=276082 - ashnazg

PhpStorm支持@return self。 - sarunast

如果我想返回子类而不是编写方法的基类，该怎么办？ - Alfred Huang

我不同意这个答案，/** @return $this */ 是唯一真正的流畅的phpdoc类型。而 @return Current_Class_Name 不是流畅的，当你从子类扩展类并调用函数时会注意到这一点。 - Daniel W.

Answer 3

这个问题很古老，但我想和大家分享！
至少对于使用NetBeans 8.1的人来说，这种符号可以使代码自动完成正常工作。

/**
 * Method that returns $this instance (using late state binding)
 * @return static
 */
 public function iWillReturnMyself ( ) {
     return $this;
 }

我说至少适用于NetBeans8.1用户，但可能也适用于旧版本和/或其他IDE =]

- Diego Calero

---

NetBeans 8.2也适用。 - Tebe

这个（在我看来是最好的选择）不幸的是在PHPStorm中无法工作。"静态字段name未找到"。 - PeterM

@PeterM，我的PHPStorm版本（2018.2）支持静态。 - Arth

也适用于 VS Code。 - Sam Tigle

这对我在VS Code上使用静态方法返回类实例有效。 - valepu

Answer 4

/**
 * set something
 *
 * @return self
 */
public function setSomething(){
            // ...
    return $this;
}

您可以在 @param 或 @return 中使用 "self" 类型。

PHPDoc 建议使用 'self' 来引用对象中的自身。

来源：http://www.phpdoc.org/docs/latest/references/phpdoc/types.html

- MURATSPLAT

---

这在子类中的效果不佳。如果子类未对其进行覆盖，解释器就不知道必须返回相同子类的对象。 - SOFe

@SOFe 在 PHPStorm 中似乎支持 @return static。 - faintsignal