W poniższym artykule chcę przybliżyć podstawy dokumentowania kodu w Php. Dzięki zastosowaniu instrukcji PhpDoc sprawiamy, że rozwój projektu oraz wdrażanie kolejnych osób jest znacznie szybsze.
Wybrałem dwa przykłady, które korzystają z podstawowych / najczęściej stosowanych instrukcji PhpDoc’a.

Przykład na widoku

Aby pokazać przykład zastosowania dokumentowania właściwości klasy w celu autouzupełniania posłużę się prostą klasą Widoku. Załóżmy, że klasa ma renderować widok przedstawiający album muzyczny w katalogu internetowym.

<?php

class AlbumView

{

protected $_data;

public function __get($name)

{

//pobiera wiersz ze zmiennej _data

}

public function render()

{

//wyświetla zawartość pliku album.phtml

}
}

Jak widać obiekt posiada metodę magiczną __get, która pobiera dane ze zmiennej $_data (załóżmy, że każdy album posiada pierwsze i drugie imię autora w wierszach _data). Problem w tym, że IDE nie podpowie nam jakie pola albumu możemy pobrać. Z pomocą przychodzi @property z PhpDoca.

Poniżej przykład użycia @property w klasie AlbumView:

<?php

/**

* @property string $authorFirstname

* @property string $authorLastname

*

*/

class AlbumView

{

Dodałem metodę getFullName, jak widać poniżej autouzupełnianie działa:

Nasza klasa widoku posiada metodę render, która wyświetla widok na podstawie pliku album.phtml. Plik widoku to tagi html z odpowiednimi wstawkami php wyświetlające dane opisujące album muzyczny. W tym przypadku IDE również nie podpowie nam jakie własności posiada obiekt $this dopóki nie utworzymy dokumentacji do tej zmiennej. W tym celu użyjemy instrukcji @var.

Efekt poniżej:

Dzięki tej jednej linii dokumentacji mamy wszystkie podpowiedzi z klasy widoku.

Dopiszmy do obiektu widoku metodę getTags.

/**

* @return array

*/

public function getTags()

{

return (array) $this->tags;

}

Metoda zwraca tablicę, której wiersze są instancjami klasy TagRow.

class TagRow
{
public $name;
}

@return wskazuje, że metoda getTags zwróci wartość w postaci array. Nie jest to pomocne gdyż wstawiając w widoku pętle foreach nie uzyskamy podpowiedzi dla obiektu $tag (obrazek poniżej):

Aby uzyskać wsparcie dla autouzupełniania w zmiennej $tag zastosujemy rozszerzenie dla @return w postaci TagRow[].

/**
* @return array|TagRow[]
*/
public function getTags()
{

IDE rozpozna tą instrukcje i w konstrukcji pętli wyświetli podpowiedzi dla obiektu $tag.

Konstrukcja określająca zawartość wiersza tablicy nie jest jeszcze rozpoznawana przez wszystkie popularne IDE, zawsze można zastosować @var dla zmiennej $tag.

Przykład na mapperze

Załóżmy, że nasza klasa Mapper za pomocą metody magicznej __call pobiera i zapisuje wiersze z tablicy $_data według schematu:

  1. getFirstname() zwróci $_data[‘firstname’]
  2. setFirstname(‘Andrzej’) wykona $_data[‘firstname’] = ‘Andrzej’

Tak jak w przypadku wcześniej utworzonej klasy widoku podpowiadanie nie zadziała. Aby autouzupełnianie dla getterów i seterów było widoczne należy zastosować instrukcję @method. Rysunek poniżej przedstawia kompletną klasę:

Struktura instrukcji @method oraz @property jest prosta, na pierwszym miejscu podajemy wartość jaka zostanie zwrócona, a na drugim nazwę metody / własności.

To zaledwie kilka zastosowań PhpDoca, przybliżyłem te najbardziej przydatne instrukcje, które są proste w użyciu i znacznie ułatwiają pracę. Polecam ich stosowanie w każdym projekcie. Więcej informacji można znaleźć na oficjalnej stronie.