Federico Cargnelutti

Annotations provide data about a program that is not part of the program itself. They have no direct effect on the operation of the code they annotate. In PHP, annotations can only be read reflectively at run time.

Basic concept of Annotations

• Add meta-data to classes, methods, properties
• Do not (directly) affect program semantics
• Can be used by tools or libraries
• Can be parameterized or simple marker annotations

Addendum is a PHP library that supports single-value and multi-value annotations. There are three annotation types:

Marker

Marker type annotations have no elements, except the annotation name itself.

Example:

class Persistent extends Annotation {}

Usage:

/** @Persistent */
class Person {
    ...
}

// by class name
$reflection = new ReflectionAnnotatedClass('Person');
// by instance
$person = new Person();
$reflection = new ReflectionAnnotatedClass($person);
// true
$reflection->hasAnnotation('Persistent');

Single-value

Single-value type annotations provide a single piece of data only. This can be represented with a data=value pair or, simply with the value (a shortcut syntax) only, within parenthesis.

Example:

class Table extends Annotation {}

Usage:

/** @Table("people") */
class Person {
    ...
}

// by class name
$reflection = new ReflectionAnnotatedClass('Person');
// contains string "people"
$reflection->getAnnnotation('Table')->value;

Multi-value

Multi-value type annotations have multiple data members. Therefore, you must use a full data=value parameter syntax for each member.

Example:

class Secured extends Annotation {
   public $role;
   public $level;
}

Usage:

/** @Secured(role = "admin", level = 2) */
class Administration {
    ...
}

// by class name
$reflection = new ReflectionAnnotatedClass('Administration');
$annotation = $reflection->getAnnnotation('Secured');
// contains string "admin"
$annotation->role;
// contains integer "2"
$annotation->level;

More information

• Advanced features
• Project Home
• Source Code

Related Projects

• AttributeReader