Как полезная аннотация для PHP?

Ответ 1

Роб Олмос объяснил это правильно:

Аннотации в основном позволяют вводить поведение и могут способствовать развязыванию.

В моих словах я бы сказал, что эти аннотации ценны, особенно в контексте reflection, где вы собираете (дополнительные) метаданные о класс/метод/свойство, которое вы проверяете.

Еще один пример вместо ORM: Framework Injection of Dependency. Предстоящая среда FLOW3 использует, например, docComments/аннотации, чтобы определить, какие объекты вставляются в экземпляр, созданный из контейнера DI, вместо указания его в XML Файл конфигурации.

Пример с упрощенным примером:

У вас есть два класса: один класс Soldier и класс Weapon. Экземпляр Weapon вводится в экземпляр Soldier. Посмотрите на определение двух классов:

class Weapon {
    public function shoot() {
        print "... shooting ...";
    }
}

class Soldier {
    private $weapon;

    public function setWeapon($weapon) {
        $this->weapon = $weapon;
    }

    public function fight() {
        $this->weapon->shoot();
    }
}

Если вы будете использовать этот класс и вручную вводите все зависимости, вы должны сделать это следующим образом:

$weapon = new Weapon();

$soldier = new Soldier();
$soldier->setWeapon($weapon); 
$soldier->fight();

Хорошо, это было много шаблонов кода (медведь со мной, я собираюсь объяснить, какие аннотации полезны довольно скоро). Структуры зависимостей для инъекций могут сделать для вас - это абстрагировать создание таких составных объектов и автоматически вводить все зависимости, вы просто выполняете:

$soldier = Container::getInstance('Soldier');
$soldier->fight(); // ! weapon is already injected

Правильно, но Container должен знать, какие зависимости имеет класс a Soldier. Таким образом, большинство общих фреймворков используют XML в качестве формата конфигурации. Пример конфигурации:

<class name="Soldier">
    <!-- call setWeapon, inject new Weapon instance -->
    <call method="setWeapon">
        <argument name="Weapon" />
    </call>
</class>

Но то, что FLOW3 использует вместо XML, представляет собой аннотации непосредственно в PHP-коде, чтобы определить эти зависимости. В FLOW3 ваш класс Soldier будет выглядеть следующим образом (синтаксис только в качестве примера):

class Soldier {
    ...

    // ---> this

    /**
     * @inject $weapon Weapon
     */
    public function setWeapon($weapon) {
        $this->weapon = $weapon;
    }

    ...

Таким образом, для контейнера DI не требуется XML для обозначения зависимости от Soldier до Weapon.

FLOW 3 использует эти аннотации также в контексте AOP, чтобы отметить методы, которые должны быть "сотканными" (означает поведение инъекций до или после метод).

Насколько я понимаю, я не слишком уверен в полезности этих аннотаций. Я не знаю, облегчает или затрудняет "скрытие" этих зависимостей и настройку в PHP-коде вместо использования отдельного файла.

Я работал e. г. в Spring.NET, NHibernate и с картой DI (не FLOW3) в PHP, как на основе файлов конфигурации XML, так и не могу сказать, что это было слишком сложно. Поддержание этих файлов настроек было в порядке.

Но, возможно, будущий проект с FLOW3 докажет обратное, а аннотации - реальный путь.

Ответ 2

Для чего это хорошо?

Аннотации в основном позволяют вводить поведение и могут способствовать развязыванию. Одним из примеров может служить ORM доктрины. Из-за использования аннотаций вам не нужно наследовать от класса, специфичного для Doctrine, в отличие от Propel ORM.

Жестко отлаживать ленивую загрузку динамического кодирования?

К сожалению, это побочный эффект, такой как большинство/все действия развязки, такие как шаблоны проектирования, переводы данных и т.д.

Хм. Мой мозг все еще не замалчивает его. - hopeeekr

Если вы не наследовали от класса Doctrine, вам, скорее всего, придется использовать некоторые другие спецификации метаданных, такие как файл конфигурации, чтобы указать, что конкретное свойство является идентификатором записи. В этом случае он будет слишком удален от синтаксиса, который описывает аннотация (метаданные).

Ответ 3

Для полноты, здесь рабочий пример использования аннотаций, а также как расширить язык PHP для их поддержки, все в одном файле.

Это "реальные" аннотации, означающие, объявленные на уровне языка, а не скрытые в комментариях. Преимущество использования аннотаций стиля Java таким образом, что они не могут быть упущены парсерами, игнорирующими комментарии.

Верхняя часть, перед __halt_compiler(); - это процессор, расширяющий язык PHP с помощью простой аннотации метода, которая кэширует вызовы методов.

Класс внизу - пример использования аннотации @cache для метода.

(этот код лучше всего читать снизу вверх).

<?php

// parser states
const S_MODIFIER  = 0;  // public, protected, private, static, abstract, final
const S_FUNCTION  = 1;  // function name
const S_SIGSTART  = 2;  // (
const S_SIGEND    = 3;  // )
const S_BODYSTART = 4;  // {
const S_BODY      = 5;  // ...}

function scan_method($tokens, $i)
{
  $state = S_MODIFIER;

  $depth = 0;  # {}

  $funcstart = $i;
  $fnameidx;
  $funcbodystart;
  $funcbodyend;
  $sig_start;
  $sig_end;
  $argnames=array();

  $i--;
  while ( ++$i < count($tokens) )
  {
    $tok = $tokens[$i];

    if ( $tok[0] == T_WHITESPACE )
      continue;

    switch ( $state )
    {
      case S_MODIFIER:
        switch ( $tok[0] )
        {
          case T_PUBLIC:
          case T_PRIVATE:
          case T_PROTECTED:
          case T_STATIC:
          case T_FINAL:
          case T_ABSTRACT:  # todo: handle body-less functions below
            break;

          case T_FUNCTION:
            $state=S_FUNCTION;
            break;

          default:
            return false;
        }
        break;

      case S_FUNCTION:
        $fname = $tok[1];
        $fnameidx = $i;
        $state = S_SIGSTART;
        break;

      case S_SIGSTART:
        if ( $tok[1]=='(' )
        {
          $sig_start = $i;
          $state = S_SIGEND;
        }
        else return false;

      case S_SIGEND:
        if ( $tok[1]==')' )
        {
          $sig_end = $i;
          $state = S_BODYSTART;
        }
        else if ( $tok[0] == T_VARIABLE )
          $argnames[]=$tok[1];
        break;

      case S_BODYSTART:
        if ( $tok[1] == '{' )
        {
          $funcbodystart = $i;
          $state = S_BODY;
        }
        else return false;
        #break;  # fallthrough: inc depth

      case S_BODY:
        if ( $tok[1] == '{' ) $depth++;
        else if ( $tok[1] == '}' )
          if ( --$depth == 0 )
            return (object) array(
              'body_start'  => $funcbodystart,
              'body_end'    => $i,
              'func_start'  => $funcstart,
              'fnameidx'    => $fnameidx,
              'fname'       => $fname,
              'argnames'    => $argnames,
              'sig_start'   => $sig_start,
              'sig_end'     => $sig_end,
            );
        break;

      default: die("error - unknown state $state");
    }
  }

  return false;
}

function fmt( $tokens ) {
  return implode('', array_map( function($v){return $v[1];}, $tokens ) );
}

function process_annotation_cache( $tokens, $i, $skip, $mi, &$instructions )
{
    // prepare some strings    
    $args  = join( ', ', $mi->argnames );
    $sig   = fmt( array_slice( $tokens, $mi->sig_start,  $mi->sig_end    - $mi->sig_start  ) );
    $origf = fmt( array_slice( $tokens, $mi->func_start, $mi->body_start - $mi->func_start ) );

    // inject an instruction to rename the cached function
    $instructions[] = array(
      'action'  => 'replace',
      'trigger' => $i,
      'arg'     => $mi->sig_end -$i -1,
      'tokens'  => array( array( "STR", "private function __cached_fn_$mi->fname$sig" ) )
    );

    // inject an instruction to insert the caching replacement function
    $instructions[] = array(
      'action'  => 'inject',
      'trigger' => $mi->body_end + 1,
      'tokens'  => array( array( "STR", "

  $origf
  {
    static \$cache = array();
    \$key = join('#', func_get_args() );
    return isset( \$cache[\$key] ) ? \$cache[\$key]: \$cache[\$key] = \$this->__cached_fn_$mi->fname( $args );
  }
      " ) ) );
}


function process_tokens( $tokens )
{
  $newtokens=array();
  $skip=0;
  $instructions=array();

  foreach ( $tokens as $i=>$t )
  {
    // check for annotation
    if ( $t[1] == '@'
      && $tokens[$i+1][0]==T_STRING    // annotation name
      && $tokens[$i+2][0]==T_WHITESPACE 
      && false !== ( $methodinfo = scan_method($tokens, $i+3) )
    )
    {
      $skip=3;  // skip '@', name, whitespace

      $ann_method = 'process_annotation_'.$tokens[$i+1][1];
      if ( function_exists( $ann_method ) )
        $ann_method( $tokens, $i, $skip, $methodinfo, $instructions );
      # else warn about unknown annotation
    }

    // process instructions to modify the code
    if ( !empty( $instructions ) )
      if ( $instructions[0]['trigger'] == $i ) // the token index to trigger at
      {
        $instr = array_shift( $instructions );
        switch ( $instr['action'] )
        {
          case 'replace': $skip = $instr['arg']; # fallthrough
          case 'inject':  $newtokens=array_merge( $newtokens, $instr['tokens'] );
            break;

          default:
            echo "<code style='color:red'>unknown instruction '{$instr[1]}'</code>";
        }
      }

    if ( $skip ) $skip--;
    else $newtokens[]=$t;
  }

  return $newtokens;
}

// main functionality

$data   = file_get_contents( __FILE__, null, null, __COMPILER_HALT_OFFSET__ );
$tokens = array_slice( token_get_all("<"."?php ". $data), 1 );
// make all tokens arrays for easier processing
$tokens = array_map( function($v) { return is_string($v) ? array("STR",$v) : $v;}, $tokens );

echo "<pre style='background-color:black;color:#ddd'>" . htmlentities( fmt($tokens) ) . "</pre>";

// modify the tokens, processing annotations
$newtokens = process_tokens( $tokens );

// format the new source code
$newcode = fmt( $newtokens );
echo "<pre style='background-color:black;color:#ddd'>" . htmlentities($newcode) . "</pre>";

// execute modified code
eval($newcode);

// stop processing this php file so we can have data at the end
__halt_compiler();

class AnnotationExample {

  @cache
  private function foo( $arg = 'default' ) {
    echo "<b>(timeconsuming code)</b>";
    return $arg . ": 1";
  }

  public function __construct() {
    echo "<h1 style='color:red'>".get_class()."</h1>";
    echo $this->foo("A")."<br/>";
    echo $this->foo("A")."<br/>";
    echo $this->foo()."<br/>";
    echo $this->foo()."<br/>";
  }
}

new AnnotationExample();

Оставаясь на примере контейнера DI (который вообще не имеет ничего общего с аннотациями), вышеупомянутый подход может также использоваться для модификации конструкторов классов, чтобы заботиться о введении любых зависимостей, что делает использование компонентов полностью прозрачным, Подход к модификации исходного кода до его оценки примерно эквивалентен "методу байт-кода" в пользовательских загрузчиках классов Java. (Я упоминаю Java с AFAIK, где впервые были введены аннотации).

Полезность этого конкретного примера заключается в том, что вместо того, чтобы вручную писать код кэширования для каждого метода, вы можете просто отметить метод, который должен быть кэширован, уменьшая количество повторяющихся действий и делая код более понятным. Кроме того, эффекты любой аннотации в любом месте можно включать и отключать во время выполнения.

Ответ 4

phpDocumentor и современные IDE используют аннотации для определения типов параметров метода (@param), возвращаемых значений (@return) и т.д.

Тестирование PhpUnit использует аннотацию для групповых тестов, определяет зависимости.