I vote for @return self since it's now used in php 7 as returned type hint

What PSR-X tells us about this?

For phpdoc see https://www.phpdoc.org/docs/latest/references/phpdoc/types.html, selfis in the list. Same for the php RFC about return type hint, self and parent https://wiki.php.net/rfc/return_types#differences_from_past_rfcs.

I was more thinking about https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md

thanks for the link, looks like self is in the Appendix A as well https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#appendix-a-types

$this is allowed

https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#appendix-a-types

> keyword = "resource" / "self" / "static" / "string" / "true" / "void" / "$this"

Didnt read well @HeahDude :)

For PHPStorm $this gives way better DX so it seems (opposed to self).

For PHPStorm $this gives way better DX so it seems (opposed to self).

How that? We use self in many projects for some time now and it works pretty well.

Changing FormConfigBuilderInterface::addEventListener from @return self to @return $this (or @return static)

😭

I personally use static everytime (because it behaves like late static binding), but according to PSR-5 Keywords section, 14-15:

static, the element to which this type applies is of the same class as which the documented element is contained, or when encountered in a subclass is of type of that subclass instead of the original class.

This keyword behaves the same way as the keyword for late static binding (not the static method, property, nor variable modifier) as defined by PHP.

$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 seems the most appropriate. 👍

self isn't because:

the element to which this type applies is of the same class as which the documented element is originally contained

which means:

it may lead to confusing situations when inheritance is involved