Чем полезна аннотация в PHP?
Чем полезна аннотация в PHP? и я не имею в виду PHPDoc в общем.
Я просто хочу пример из жизни или что-то подобное, я думаю.
Итак, согласно ответу @Max: аннотации выполняют то же самое, что и абстрактные фабрики, только через одну строку специализированного PHPDoc. - hopeseekr 0 секунд назад редактировать
4 ответа
Роб Олмос правильно объяснил:
Аннотации в основном позволяют вводить поведение и могут способствовать разделению.
В моих словах я бы сказал, что эти аннотации являются ценными, особенно в контексте размышлений, когда вы собираете (дополнительные) метаданные о классе / методе / свойстве, которое вы проверяете.
Другой пример вместо ORM: Внедрение зависимостей. Например, будущая инфраструктура FLOW3 использует docComments/annotations для определения, какие объекты внедряются в экземпляр, созданный из контейнера 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 должен знать, какие зависимости 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;
}
...
Таким образом, не требуется XML для обозначения зависимости Soldier в Weapon для контейнера DI.
FLOW 3 использует эти аннотации также в контексте AOP, чтобы пометить методы, которые должны быть "сотканы" (означает введение поведения до или после метода).
Что касается меня, я не слишком уверен в полезности этих аннотаций. Я не знаю, облегчает ли это ситуацию или хуже, "скрывая" такие зависимости и настройки в PHP-коде вместо использования отдельного файла.
Я работал, например, в Spring.NET, NHibernate и с инфраструктурой DI (не FLOW3) в PHP, основанной на файлах конфигурации XML, и не могу сказать, что это было слишком сложно. Поддерживать эти установочные файлы тоже было нормально.
Но, возможно, будущий проект с FLOW3 доказывает обратное, и аннотации - это реальный путь.
Именно для чего это нужно?
Аннотации в основном позволяют вводить поведение и могут способствовать разделению. Одним из примеров будет доктрина ОРМ. Из-за использования аннотаций вам не нужно наследовать от класса, специфичного для Doctrine, в отличие от Propel ORM.
Трудно отладить ленивую загрузку динамического кодирования?
К сожалению, это побочный эффект, такой как большинство / все действия развязки, такие как шаблоны проектирования, переводы данных и т. Д.
Хм. Мой мозг все еще не работает. - hopeseekr
Если вы не унаследовали класс Doctrine, вам, скорее всего, придется использовать некоторую другую спецификацию метаданных, например файл конфигурации, чтобы указать, что конкретное свойство является идентификатором записи. В этом случае это будет слишком далеко от синтаксиса, который описывает аннотация (метаданные).
Для полноты картины, вот рабочий пример того, как использовать аннотации, а также как расширить язык 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, именно здесь впервые были представлены аннотации).
Полезность этого конкретного примера состоит в том, что вместо того, чтобы вручную писать код кэширования для каждого метода, вы можете просто пометить метод как необходимый для кэширования, сократив количество повторяющихся операций и сделав код более понятным. Кроме того, эффекты любой аннотации в любом месте можно включать и выключать во время выполнения.
phpDocumentor и современные IDE используют аннотации для определения типов параметров метода (@param), возвращаемых значений (@return) и так далее.
PhpUnit Testing использует аннотацию для группировки тестов, определения зависимостей.