Custom Annotation Classes

Inject annotation values

The annotation parser checks if the annotation constructor has arguments, if so then it will pass the value array, otherwise it will try to inject values into public properties directly:

1
namespace MyCompany\Annotations;

/**
 * @Annotation
 *
 * Some Annotation using a constructor
 */
class Bar
{
    private $foo;

    public function __construct(array $values)
    {
        $this->foo = $values['foo'];
    }
}

/**
 * @Annotation
 *
 * Some Annotation without a constructor
 */
class Foo
{
    public $bar;
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

Annotation Target

@Target indicates the kinds of class elements to which an annotation type is applicable. Then you could define one or more targets:

• CLASS Allowed in class docblocks
• PROPERTY Allowed in property docblocks
• METHOD Allowed in the method docblocks
• ALL Allowed in class, property and method docblocks
• ANNOTATION Allowed inside other annotations

If the annotations is not allowed in the current context, an AnnotationException is thrown.

1
namespace MyCompany\Annotations;

/**
 * @Annotation
 * @Target({"METHOD","PROPERTY"})
 */
class Bar
{
    // some code
}

/**
 * @Annotation
 * @Target("CLASS")
 */
class Foo
{
    // some code
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Attribute types

The annotation parser checks the given parameters using the phpdoc annotation @var, The data type could be validated using the @var annotation on the annotation properties or using the @Attributes and @Attribute annotations.

If the data type does not match you get an AnnotationException

1
namespace MyCompany\Annotations;

/**
 * @Annotation
 * @Target({"METHOD","PROPERTY"})
 */
class Bar
{
    /** @var mixed */
    public $mixed;

    /** @var boolean */
    public $boolean;

    /** @var bool */
    public $bool;

    /** @var float */
    public $float;

    /** @var string */
    public $string;

    /** @var integer */
    public $integer;

    /** @var array */
    public $array;

    /** @var SomeAnnotationClass */
    public $annotation;

    /** @var array<integer> */
    public $arrayOfIntegers;

    /** @var array<SomeAnnotationClass> */
    public $arrayOfAnnotations;
}

/**
 * @Annotation
 * @Target({"METHOD","PROPERTY"})
 * @Attributes({
 *   @Attribute("stringProperty", type = "string"),
 *   @Attribute("annotProperty",  type = "SomeAnnotationClass"),
 * })
 */
class Foo
{
    public function __construct(array $values)
    {
        $this->stringProperty = $values['stringProperty'];
        $this->annotProperty = $values['annotProperty'];
    }

    // some code
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

Annotation Required

@Required indicates that the field must be specified when the annotation is used. If it is not used you get an AnnotationException stating that this value can not be null.

Declaring a required field:

1
/**
 * @Annotation
 * @Target("ALL")
 */
class Foo
{
    /** @Required */
    public $requiredField;
}
2
3
4
5
6
7
8
9

Usage:

1
/** @Foo(requiredField="value") */
public $direction;                  // Valid

 /** @Foo */
public $direction;                  // Required field missing, throws an AnnotationException
2
3
4
5

Enumerated values

• An annotation property marked with @Enum is a field that accepts a fixed set of scalar values.
• You should use @Enum fields any time you need to represent fixed values.
• The annotation parser checks the given value and throws an AnnotationException if the value does not match.

Declaring an enumerated property:

1
/**
 * @Annotation
 * @Target("ALL")
 */
class Direction
{
    /**
     * @Enum({"NORTH", "SOUTH", "EAST", "WEST"})
     */
    public $value;
}
2
3
4
5
6
7
8
9
10
11

Annotation usage:

1
/** @Direction("NORTH") */
public $direction;                  // Valid value

 /** @Direction("NORTHEAST") */
public $direction;                  // Invalid value, throws an AnnotationException
2
3
4
5

Constants

The use of constants and class constants is available on the annotations parser.

The following usages are allowed:

1
namespace MyCompany\Entity;

use MyCompany\Annotations\Foo;
use MyCompany\Annotations\Bar;
use MyCompany\Entity\SomeClass;

/**
 * @Foo(PHP_EOL)
 * @Bar(Bar::FOO)
 * @Foo({SomeClass::FOO, SomeClass::BAR})
 * @Bar({SomeClass::FOO_KEY = SomeClass::BAR_VALUE})
 */
class User
{
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Be careful with constants and the cache !

Usage

Using the library API is simple. Using the annotations described in the previous section, you can now annotate other classes with your annotations:

1
namespace MyCompany\Entity;

use MyCompany\Annotations\Foo;
use MyCompany\Annotations\Bar;

/**
 * @Foo(bar="foo")
 * @Bar(foo="bar")
 */
class User
{
}
2
3
4
5
6
7
8
9
10
11
12

Now we can write a script to get the annotations above:

1
$reflClass = new ReflectionClass('MyCompany\Entity\User');
$classAnnotations = $reader->getClassAnnotations($reflClass);

foreach ($classAnnotations AS $annot) {
    if ($annot instanceof \MyCompany\Annotations\Foo) {
        echo $annot->bar; // prints "foo";
    } else if ($annot instanceof \MyCompany\Annotations\Bar) {
        echo $annot->foo; // prints "bar";
    }
}
2
3
4
5
6
7
8
9
10

You have a complete API for retrieving annotation class instances from a class, property or method docblock:

1
public function getClassAnnotations(\ReflectionClass $class);

1
public function getClassAnnotation(\ReflectionClass $class, $annotationName);

1
public function getMethodAnnotations(\ReflectionMethod $method);

1
public function getMethodAnnotation(\ReflectionMethod $method, $annotationName);

1
public function getPropertyAnnotations(\ReflectionProperty $property);

1
public function getPropertyAnnotation(\ReflectionProperty $property, $annotationName);