Anotace

Anotace jsou speciálním druhem komentářů, který rozšiřuje schopnosti PHP o další funkcionalitu.

Anotace se píší do phpDoc/JavaDoc bloků a začínají vždy @. V Nette Frameworku se s nimi pracuje pomocí Reflexí. Nette implementuje vlastní anotační parser, takže by neměl nastat problém s různými akcelerátory, které kvůli zrychlení scriptu „mažou“ komentáře.

Ukázkový kód

Toto jsou dvě ukázkové třídy, se kterými budeme v následujícím textu pracovat.

/**
 * @author John Doe
 * @author Tomas Marny
 * @renderable
 * @title(value = 'Three (Four)', mode = 'false')
 */
class FooClass
{
    /** @secured */
    public $foo;

    /** @AJAX */
    public function foo() {}
}

/**
 * @author Franta Vomacka
 */
class BarClass extends FooClass
{
    /**
     * @privilege(Bar, bar)
     * @description(testing)
     * @more info, test
     */
    public function bar() {}
}

Typy anotací

Anotace dělíme podle dvou kritérií: podle toho, které části kódu se týkají (třída, funkce, vlastnost, metoda) a podle stylu zápisu.

1. @secured
2. @author John Doe
3. @privilege(Bar, bar)

První anotace je typu boolean. To znamená, že pokud je přítomna, obsahuje hodnotu TRUE. Druhá je typu string, nese tedy textovou hodnotu. A třetí, ta nejzvláštnější, by se mohla na první pohled zdát jako pole, ale není tomu vždy tak.

• @foo() – obsahuje boolean hodnotu TRUE
• @foo(test) – obsahuje řetězec „test“
• @foo(bar, test) – obsahuje pole řetězců „bar“ a „test“
• @foo(value = 'Three (Four)', mode = 'false') – obsahuje asociativní pole párů 'value' => "Three (Four)" a 'mode' => "false"

Pokud chcete pokaždé získat data jako pole, stačí výsledek přetypovat: (array) $reflection->getAnnotation('foo')

Práce s anotacemi

Ověření existence anotace

Zda daná třída obsahuje danou anotaci zjistíme tak, že zavoláme metodu Nette\Reflecti­on\ClassReflec­tion::hasAnno­tation() a jako parametr uvedeme název anotace (v našem případě je to renderable).

$fooReflection = new Nette\Reflection\ClassReflection('FooClass'); //získáme reflexní třídu třídy FooClass
$fooReflection->hasAnnotation('renderable'); //vrátí TRUE
$fooReflection->hasAnnotation('exist'); //vrátí FALSE

Získání anotace

Data anotace získáme zavoláním metody Nette\Reflecti­on\ClassReflec­tion::getAnno­tation() kde jako parametr opět uvedeme název anotace.

$fooReflection = new Nette\Reflection\ClassReflection('FooClass'); //získáme reflexní třídu třídy FooClass
$fooReflection->getAnnotation('author'); // vrátí řetězec "Tomas Marny"

Pro lepší pochopení si ukážeme ještě získání anotace metody BarClass::bar().

$barReflection = new Nette\Reflection\MethodReflection('BarClass', 'bar'); //získáme reflexní třídu metody BarClass::bar()
$barReflection->getAnnotation('privilege'); // vrátí array("Bar", "bar")

Vždy se vypíše pouze poslední definice anotace, předchozí se přepíše.

Získání dat všech anotací

Data všech anotací získáme zavoláním metody Nette\Reflecti­on\ClassReflec­tion::getAnno­tations().

$fooReflection = new Nette\Reflection\ClassReflection('FooClass'); //získáme reflexní třídu třídy FooClass
$fooReflection->getAnnotations();

array(3) {
   "author" => array(2) {
      0 => string(8) "John Doe"
      1 => string(11) "Tomas Marny"
   }
   "renderable" => array(1) {
      0 => bool(TRUE)
   }
   "title" => array(1) {
      0 => object(ArrayObject) (2) {
         "value" => string(12) "Three (Four)"
         "mode" => string(5) "false"
      }
   }
}

Výsledkem je pole anotací „author“ a „renderable“, které samy obsahují pole hodnot. Pro lepší pochopení si ukážeme ještě získání anotací k metodě BarClass::bar().

$barReflection = new Nette\Reflection\MethodReflection('BarClass', 'bar'); //získáme reflexní třídu metody BarClass::bar()
$barReflection->getAnnotations();

array(3) {
   "privilege" => array(1) {
      0 => object(ArrayObject) (2) {
         "0" => string(3) "Bar"
         "1" => string(3) "bar"
      }
   }
   "description" => array(1) {
      0 => string(7) "testing"
   }
   "more" => array(1) {
      0 => string(10) "info, test"
   }
}

Dědičnost anotací

Anotace se nepřenáší na potomky třídy, ale můžete jich použít více stejných nad jednou třídou.

---

Login to submit a comment