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.

phpdoc w służbie IDE
Tagged on:                 

One thought on “phpdoc w służbie IDE

  • 2012-01-01 at 01:03
    Permalink

    Tak się składa że opisywałem to na Di.com.pl tutaj: http://di.com.pl/news/37332,0,PhpDoc_%E2%80%93_ulatwiajmy_sobie_i_innym_zycie.html

    phpStorm w pełni obsługuje phpDoc i dzisiaj nie wyobrażam sobie pisania bez robienia dokumentacji. Dodatkowo oprócz tego o czym pisałeś można sobie pomagać bezpośrednio w kodzie wskazując typ zmiennych. Taki komentarz inline jak

    /** @var SuperObj $test */

    sprawi że zmienna $test będzie traktowana jako instancja SuperObj i tak też będzie się zachowywało podpowiadanie składni.
    Również jak napisałem w artykule, tworząc takie zapisy jak

    /** @var foo | bar[] */

    sprawisz że inne podpowiadanie będziesz miał jak dany atrybut użyjesz jako zmienną a inaczej gdy użyjesz go jako obiekt.

    Cała masa tego jest. Warto zobaczyć co nasze IDE potrafi i warto wiedzieć jak dokumentować kod. Dla siebie i innych.

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Social Widgets powered by AB-WebLog.com.