Short Tutorial By Example

Addendum annotation basics

Creating your first annotation

Annotations in Addendum are simple classes. To make a new Persistent annotation all you need to do is:

class Persistent extends Annotation {}

NOTE: Make sure that annotation class name starts with an uppercase letter.

Annotating a class

With this defined annotation, you can annotate a different class/method/property with it. Annotating in Addendum is done by creating a doc block comment with annotation syntax you might know from Java.

/** @Persistent */
class Person {
   // some code
}

NOTE: Please make sure that there are two asterisks at beginning. Doc blocks differ from normal comments.

Accessing annotations

Annotations of a class are accessed through extended reflection API. A reflecting class can be created in two ways:

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

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

To find out if a class is annotated by Persistent annotation use:

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

To access method/property annotations you can use ReflectionAnnotatedMethod and ReflectionAnnotatedProperty.

Valued annotations

Single valued annotation

An annotation can also hold a value. Let us create a Table annotation to demonstrate this feature.

class Table extends Annotation {}

Now let us annotate a class with a valued annotation.

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

This value can be then accessed through reflection API

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

Multi valued annotation

Annotations can also hold multiple values. A multi valued annotation can be defined easily like this

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

Multi valued annotations are used like this:

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

To access these field just use extended reflection API.

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

Array values in annotations

Annotations can even hold arrays of values using {} syntax. For example:

class RolesAllowed extends Annotation {}

/** @RolesAllowed({'admin', 'web-editor'}) */
class CMS {
 // some code
}

$reflection = new ReflectionAnnotatedClass('CMS');
$annotation = $reflection->getAnnotation('RolesAllowed');
$annotation->value; // contains array('admin', 'web-editor')

Of course you can also use associative arrays.

@Annotation({key1 = 1, key2 = 2, key3 = 3})

Or even mix them and use nested arrays any way you like!

@Annotation({key1 = 1, 2, 3, {4, key = 5}})

And there is more!

If your head is not spinning now look at more advanced features.