PHP code completion and PHPDoc

I love code completion. It makes my life easier. I can finish my work faster, let alone the nice feeling you have when you see it work. It makes me feel like putting the final piece in tetris.

Yet, when it comes to weakly typed languages like php, its implementation is not easy. The IDEs cannot derive all the required information from the code, so they have to resort to other techniques. One of the most common is to take advantage of annotated comments, which in the case of php are defined by PHPDocumentator, an open source tool.

However, we must never forget that PHPDocumentator was not designed with code completion in mind. It’s a topic out of its scope. So, I believe that some extensions to the standard have to be made.

The single most wanted extention is the ability to use the self and the static keywords as legal replacements of class names, the same way this is allowed in php code. There are two design patterns that would benefit from it: the Factory pattern and the Fluent Interface.

Simple example:

class Control {

    /** @return static */
     public static function Make() {      // factory pattern
      return new static();
    }

    private $label;

    /** @return static */
     public function WithLabel($value) {    // fluent interface
      $this->label = $value;
      return $this;
    }

    public function Render() {
      // rendering happens here…
    }

}

class Textbox extends Control {

    private $text;

    /** @return static */
      public function WithText($value) {   // fluent interface
        $this->text = $value;
        return $this;
    }

}

 And here is who one could use these classes:

Textbox::Make()           // <– late static binding, returns Textbox
    ->WithLabel(‘foo’)    // <– late dynamic binding, returns Textbox
    ->WithText(‘bar’)      // <– normal binding, returns Textbox
    ->Render();

Currently, IDEs have no way to determine the return type of the first call, and so cannot offer code completion for any of the following calls.

Many suggest the use of an undocumented feature of PHPDocumentator, which is @return $this . This idea has some flaws:

  1. It is not semanticaly correct, because $this stands for an object not for a class.
  2. It cannot be used in static methods
  3. The current implementation incorrectly substitutes it with method’s class (that is the class self) without taking into account late binding (that would result in the class static).

Let’s hope that the inclusion of self and static  will be implemented soon to make life easier by a tiny bit.

About these ads

2 thoughts on “PHP code completion and PHPDoc

  1. I always use “@return TextBox”, for example. I was under the impression that this is the correct, already-supported way of doing what you’re describing.

    I’m not a big user of code-completion lately, but when I was using Netbeans I’m pretty sure this syntax worked really nicely.

    • “@return Textbox” is correct but insufficient. In the class “Control” you don’t know what the subclasses are going to be. “Textbox” is just one of them, but there could be others, like “Selectbox”, “Checkbox” etc. The final class is going to be determined by late binding. This is why we need dynamic keywords, such as “static” – what an irony, “static” is “dynamic”… :-)

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s