13

How do I mark a method as "returns an instance of the current class" in my phpDoc?

In the following example my IDE (Netbeans) will see that setSomething always returns a foo object.

But that's not true if I extent the object - it'll return $this, which in the second example is a bar object not a foo object.

class foo {
    protected $_value = null;

    /**
     * Set something
     *
     * @param string $value the value
     * @return foo
     */
    public function setSomething($value) {
        $this->_value = $value;
        return $this;
    }
} 

$foo = new foo();
$out = $foo->setSomething();

So fine - setSomething returns a foo - but in the following example, it returns a bar..:

class bar extends foo {
    public function someOtherMethod(){}
}

$bar = new bar();
$out = $bar->setSomething();
$out->someOtherMethod(); // <-- Here, Netbeans will think $out
                         // is a foo, so doesn't see this other
                         // method in $out's code-completion

... it'd be great to solve this as for me, code completion is a massive speed-boost.

Anyone got a clever trick, or even better, a proper way to document this with phpDoc?

2
  • 2
    That would be NetBeans' fault, since in PHP there is no upcasting and downcasting an object.
    – BoltClock
    Jan 16, 2011 at 14:13
  • I think this is probably closest to the answer (i.e. I can't do this without some horrible compromise). I suppose in Java I would have to upcast the result of setSomething to a bar before I could use someOtherMethod on it.
    – ledneb
    Jan 18, 2011 at 9:40

5 Answers 5

10

Update:

As of Netbeans 7.4, the IDE supports @return self, static, and this (http://wiki.netbeans.org/NewAndNoteworthyNB74#Editor_2).

class foo {
    protected $_value = null;

    /**
     * Set something
     *
     * @param string $value the value
     * @return this
     */
    public function setSomething($value) {
        $this->_value = $value;
        return $this;
    }
}

class bar extends foo {
    public function someOtherMethod(){}
}

Previous Answer:

We have a similar issue with a record iterator's current() method. Since the iterator is extended for many different classes, it doesn't make sense to have a @return $class associated with it. We've used @satrun77's Option 2 before, but I've used @method with some success in Netbeans.

class foo {
    protected $_value = null;

    /**
     * Set something
     *
     * @param string $value the value
     * @return foo
     */
    public function setSomething($value) {
        $this->_value = $value;
        return $this;
    }
}

/**
 * @method bar setSomething($value)
 */
class bar extends foo {
    public function someOtherMethod(){}
}
2
  • Luckily, for those who still didn't make the leap towards the 7.4 due to the well known font rendering issue, this syntax works in Netbeans 7.3.1 as well. Jan 25, 2014 at 18:27
  • Is there a way to do something like this[] as return value?
    – tcigler
    Mar 14, 2015 at 17:20
5

Thought I'd revisit this Q as I came across a couple of things.

Currently "return $this" isn't supported, but there is a PhpDoc request to add exactly that in v1.5:

http://pear.php.net/bugs/bug.php?id=16223

There's also a request for it in Eclipse PDT:

https://bugs.eclipse.org/bugs/show_bug.cgi?id=276082

Both are relatively old requests. I'm not going to get too excited about this being implemented any time soon, but here goes to hoping :) In the meantime, it seems there is no proper solution to this problem.

2

!SOLVED! - upgrade to netbeans 9.0 (stable as of July 2018?)

I have been after this for over a year and finally have an open source solution! :)

class Input extends BasicHtml
{    
    public function someOnlyInputFunc()
    {

    }
}

class Table extends BasicHtml
{
    public function tableOnlyFunc()
    {

    }
}

abstract class BasicHtml
{

    /**
     * 
     * @param array $arrayForNow
     * @return $this
     */
    public function setStyle( array $arrayForNow )
    {        
        return $this;
    }
}


/////driver
$table = new Table();
$input = new Input();
$input->setStyle(array())->//now shows only Input + baseHtml functions
$table->setStyle(array())-> //now shows only Table + baseHtml functions
///note - in 8.0.2 version it shows blank obj drop downs on exact same code.

This also works with traits. As of 11/1/2018 9.0 comes as a big zip (no clean installer for windows, mac?) and you will have to search for adding the php plugings etc BUT IT DOES WORK! Took me about an hour to get it all set. I also have my old 8.x installed and running along side the new 9.0 without issue...so far (just don't run them both at same time). Plugin tip: https://www.reddit.com/r/PHP/comments/9gtaaw/how_to_run_netbeans_9_with_php_support/

1

Here is 3 work around: (These are just work around. classes must not be designed and implemented to sue the behavior of an IDE)

Option 1: make the method someOtherMethod abstract or empty method in foo class

class foo implements ifoo {
    protected $_value = null;

    /**
     * Set something
     *
     * @param string $value the value
     * @return ifoo
     */
    public function setSomething($value) {
        $this->_value = $value;
        return $this;
    }

    // abstract method or create empty method if you want the method to be
    // to be optional 
    abstract function someOtherMethod();
}

Option 2:

Override the method setSomething in bar class

class bar extends foo {
    /**
     *
     * @param <type> $value
     * @return bar
     */
    public function setSomething($value) {
        return parent::setSomething($value); 
    }

    public function someOtherMethod(){}
}

Option 3: Use interface

interface ifoo {
    public function someOtherMethod(){}
}

class foo {
    protected $_value = null;

    /**
     * Set something
     *
     * @param string $value the value
     * @return ifoo
     */
    public function setSomething($value) {
        $this->_value = $value;
        return $this;
    }
}

class bar extends foo implements ifoo {

    public function someOtherMethod(){}
}
1
  • Option 2 is probably the best idea here but as you say, they're all work-arounds which involve changing the extending classes when the base class changes. I think the truth is what I want to happen is a limitation of Netbeans/phpDoc. It's hard to say it's Netbeans' fault as the phpDoc does explicitly say it returns a foo. Perhaps some sort of @return $this syntax would be good..? :-S
    – ledneb
    Jan 18, 2011 at 9:43
1

phpDoc syntax allows for multiple types to be defined by separating them with a | character for the @return tag. When you extend the class foo with class bar you should write a new phpDoc tag that has the proper class for its @return.

If a function returns either foo or bar then you would use @return foo|bar.

However in your case just define @return bar for the overridden function.

Take care.

1
  • Indeed - but I wouldn't want setSomething in foo to be documented as @return foo|bar|every-other-extending-class. I was hoping to avoid having to rewrite the phpDoc for every subclass but looks like that would be the only way to have the IDE understand.
    – ledneb
    Jan 18, 2011 at 9:36

Your Answer

Reminder: Answers generated by Artificial Intelligence tools are not allowed on Stack Overflow. Learn more

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.