$this in Return-Annotation

[SenseException]

During My work on a PR for a PHP library I found a strange behaviour when it comes to Abstract classes using @return $this in a method's annotation.

abstract class MyAbstract
{
     /**
      * @return $this
      */
     public function setHandler($handler)
     {

is extended by 2 other classes: My\Namespace\Class and My\Namespace\OtherClass. In a builder for commands, I have the following code:

class Command
{
     public function buildStuff()
     {
         $this->beginCommand('stuff') // creates instance of My\Namespace\Class hardcoded in beginCommand()
             ->setHandler(function() {})
             ->methodName()
             ->moreMethods()

I get this message from Scrutinizer:

The method methodName does only exist in My\Namespace\Class, but not in My\Namespace\OtherClass. 

maybe because it is expected that My\Namespace\OtherClass should also contain methodName().

Shouldn't $this in the annotation only refer to the instance where setHandler() was invoked?

[aik099]

The @return $this is incorrect way of writing this and isn't supported by PhpDoc either. In ZendFramework this way was very popular however. The correct way would be @return static.

[SenseException]

Hi @aik099,

$this is going to be part of PSR-5 (https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#appendix-a-types at the bottom).

[SenseException]

@scrutinizer-ci Would you consider implementing @return $this?

[webmozart]

I would also like to see this!

[SenseException]

It seems that there was no answer yet. If @scrutinizer-ci is kind of occupied with other work, is there a way where I can implement this feature and create a PR? I appreciate feedback if I may be of help to Scrutinizer.