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

php documentation phpdoc doc
lucaswxp picture lucaswxp · Aug 4, 2011 · Viewed 15.4k times · Source

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

g . picture g . · Oct 30, 2015

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.

Related questions

phpDoc class constants documentation

How do I document class constants for phpDoc? I've read the manual but I can't find anything about them.

Read More
PHPDoc documentation generator in or out of Eclipse?

I am developing with Eclipse + PDT. I've been adding phpdoc comments into my code, but actually never generated a resulting documentation in Eclipse. How should I do it - is there some functionality in Eclipse, or doc generation should be …

Read More
How do I put blocks of PHP code into a PHPDoc DocBlock

I'm playing around with PHPDoc and have realised that you can use markdown to add some formatting to a DocBlock. In particular, I notice that you can use back ticks to highlight inline code. However, I can't seem to figure …

Read More