Should I use @return self, this or the current class? [closed]

Question

I have a method that return the current object, how do I document this?

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

Or should I do @return self or @return Current_Class_Name?

---

Reason why this question is not "primarily opinion-based" (and should be reopened): conformance to standards and IDE type hinting support.

Answer 1

There is a PHP Standards Recommendation (PSR) currently in draft (PSR-5) that proposes @return $this is used in order to indicate that the same instance is returned.

$this, the element to which this type applies is the same exact instance as the current class in the given context. As such this type is a stricter version of static as, in addition, the returned instance must not only be of the same class but also the same instance.

This type is often used as return value for methods implementing the Fluent Interface design pattern.

This notation is currently used by popular IDEs such as PhpStorm and Netbeans.