phpdoc w służbie IDE

Do tworzenia aplikacji w języku php używałem na początku Eclipse PDT, jednak od ponad roku przesiadłem się na Jetbrains PhpStorm. Obecnie to IDE dostępne jest w najnowszej wersji 3.0.

Przez cały czas jednak zastanawiałem się, w jaki sposób rozwiązać problem podpowiadania składni w sytuacji, gdy metoda zwraca nam tablicę obiektów. Dla przykładu:

class Foo {
  private $foo;

  public static function getAllFooObjects() {
    $availableFoos = array( 'foo_1', 'foo_2', 'foo_3' );
    $output = array();

    foreach( $availableFoos as $foo ) {
      $output[] = new self( $foo );
    }
    return $output;
  }

  public function __construct( $foo ) {
    $this.foo = $foo;
  }

  public function getFoo() {
    return $this->foo;
  }
}

Przykład może nie jest jakiś rewelacyjny jednak będzie dość dobrze obrazował rozwiązanie, które chcę zaprezentować. Załóżmy teraz, że w klasie Bar, poprzez wywołanie statycznej metody getAllFooObjects, chcemy pobrać tablicę dostępnych obiektów Foo.

class Bar {
  private $foos;

  public function __construct() {
    $this->foos = Foo::getAllFooObjects();
  }

  public function display() {
    foreach( $this->foos as $foo ) {
      echo $foo->getFoo();
    }
  }
}

Obiekty zostaną pobrane, jednak załóżmy, że chemy przeiterować zmienną $this->foos i wyświetlić zawartość zmiennej $foo każdego obiektu, czyli wywołać na każdym z nich metodę getFoo() – tak jak to przedstawiłem w metodzie display(). Oczywiście powyższy kod zadziała bez problemu. Jednak podczas jego tworzenia nasze IDE nie podpowie nam składni, ani metody getFoo wywoływanej na obiekcie $foo.

Rozwiązanie jednak jest dość proste i przychodzi nam z pomocą phpdoc. Otóż wystarczy metodę getAllFooObjects poprzedzić następującą annotacją:

/**
* @return Foo[]
* /
public static function getAllFooObjects()

Informacja taka wskazuje naszemu IDE, że dana funkcja zwróci nam tablicę obiektów klasy Foo.