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

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.

related, for static: http://stackoverflow.com/questions/5858031/phpdoc-and-late-static-or-dynamic-binding — Greg, Jan 17 '13 at 21:06

score 52 · Answer 1 · edited Jun 20 '20 at 09:12

52

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.

edited Jun 20 '20 at 09:12

Community

1
1

answered Oct 30 '15 at 14:05

g .

8,110
5
38
48

3

Your answer is misleading because it sounds like this PSR recommends `$this`. I don't think this is true. It simply *allows* it, just like `Current_Class_Name` and `self`. – marcv Nov 03 '16 at 06:53
Also note that it is `@return $this` not `@return this` as the question asked. – SOFe Dec 21 '16 at 17:39
1

I use PHP Storm and $this upsets it, whereas self and \Class do not – David Yell Jul 19 '17 at 10:05
3

Please note that PSR-5 is abandoned. – Anthony Mar 19 '18 at 08:50
@AnthonyB not anymore, for example see this PR https://github.com/php-fig/fig-standards/pull/1104 and discussion https://groups.google.com/forum/#!topic/php-fig/W1VyAtoqGQ8 – sanmai Oct 21 '18 at 04:35
@sanmai I confirm, PSR-5 is no longer abandoned, it's in [draft](https://www.php-fig.org/psr/#draft) now. Thank your for this point. – Anthony Oct 21 '18 at 07:40
@DavidYell at least since 2018 `@return $this` works better than any other class return type, with proper resolution of any inheritance. – Daniel W. Jun 08 '20 at 19:13
phpstan (PHP Static Analysis Tool) also prefers `@return $this` – Sven Mar 05 '21 at 08:54

score 32 · Accepted Answer · edited Apr 28 '14 at 11:48

32

@return Current_Class_Name will definitely work and is what I prefer.

@return self may work ok with some programs too.

@return this is bad because this is not a typename.

edited Apr 28 '14 at 11:48

Redzarf

2,578
4
30
40

answered Aug 04 '11 at 17:06

RiaD

46,822
11
79
123

1

"return Current_Class_Name" works best at the moment, as it will allow IDE autocompletion to succeed. There are feature requests in for phpDocumentor [1] and Eclipse PDT [2] to recognize "return $this". [1] -- http://pear.php.net/bugs/bug.php?id=16223 [2] -- https://bugs.eclipse.org/bugs/show_bug.cgi?id=276082 – ashnazg Aug 12 '11 at 21:50
3

PhpStorm does support `@return self` – sarunast Aug 06 '14 at 09:11
14

What if I want to return the subclass but not the base class where I write the method? – Alfred Huang May 12 '16 at 03:43
2

I disagree with this answer, `/** @return $this */` is the only real fluent phpdoc type. While `@return Current_Class_Name` is not fluent and you will notice that when extending the class and calling the function from a child. – Daniel W. Jun 08 '20 at 19:08

score 10 · Answer 3 · answered May 11 '16 at 07:00

10

This question is quite old, but I just want to share to everyone!

AT LEAST for the ones that uses NetBeans 8.1.. this notation makes code autocompletion to nicely work at IDE:

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

I say AT LEAST for NetBeans8.1 users, but may work on older versions and/or others IDEs too =]

answered May 11 '16 at 07:00

Diego Calero

134
1
4

1

for netbeans 8.2 works too – Tebe Aug 18 '17 at 07:30
This (imo, best option) unfortunately does not work in PHPStorm. "Field `name` not found in static". – PeterM Apr 17 '18 at 06:31
1

@PeterM PHPStorm supports static here on my version (2018.2) – Arth Aug 24 '18 at 17:54
1

Also works for VS Code – Sam Tigle Apr 20 '21 at 08:57
this worked for me on VS code with a static method returning an instance of the class – valepu May 14 '22 at 10:31

score 8 · Answer 4 · answered Sep 22 '15 at 20:08

8

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

You can use "self" type as @param or @return..

PHPDoc recommends 'self' to refer to self in object..

Source: http://www.phpdoc.org/docs/latest/references/phpdoc/types.html

answered Sep 22 '15 at 20:08

MURATSPLAT

4,650
1
13
12

1

This works with subclasses poorly. If the subclass doesn't override it, interpreters do not know that an object with the same subclass must be returned. – SOFe Dec 21 '16 at 17:38
1

@SOFe `@return static` appears to be supported by PHPStorm. – faintsignal Jul 10 '18 at 21:57

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

4 Answers4

Linked

Related