É indiscutível a agilidade e facilidade de configuração que as annotations provêm no Java, e com o objetivo de trazer tal comodidade ao PHP surgiu o projeto Addendum – escrito por Jan Suchal – que permite via Reflection acessar as annotations das classes.

As annotations devem ser escritas em blocos de comentários, uma vez que o @ (caracter que inicia uma annotation) é um caractere reservado no PHP. Elas podem ser mono ou multi valoradas de acordo com os exemplos abaixo.

// Custom annotation
class Persistent extends Annotation {}

// Custom annotation
class Table extends Annotation {}

// Multi valued annotation
class Secured extends Annotation {
   public $role;
   public $level;
}

/**
 * @Persistent
 * @Table("people")
 * @Secured(role = "admin", level = 2)
 */
class Person {
   // some code
}

// getting the annotation by class name
$reflection = new ReflectionAnnotatedClass('Person');

// getting the annotation by instance
$person = new Person();
$reflection = new ReflectionAnnotatedClass($person);

// true
$reflection->hasAnnotation('Persistent'); 

// contains string "people"
$reflection->getAnnotation('Table')->value; 

E seguindo na mesma onda da JPA, a versão 2.0 do projeto Doctrine implementou também a mesma funcionalidade e agora possui suas próprias annotations facilitando a configuração das classes de persistência e seus relacionamentos.

/**
 * @DoctrineEntity(tableName="cms_articles")
 */
class CmsArticle {

   /**
    * @DoctrineId
    * @DoctrineColumn(type="integer")
    * @DoctrineIdGenerator("auto")
    */
   public $id;

   /**
    * @DoctrineColumn(type="varchar", length=255)
    */
   public $topic;

   /**
    * @DoctrineColumn(type="varchar")
    */
   public $text;

   /**
    * @DoctrineManyToOne(targetEntity="CmsUser",
           joinColumns={"user_id" = "id"})
    */
   public $user;

   /**
    * @DoctrineOneToMany(targetEntity="CmsComment", mappedBy="article")
    */
   public $comments;
}

Posts relacionados:

1. PHP: Socket Class
2. Paradigma Orientado a Objetos