This library provides parsing for annotations defined in class, method and member doc comments. Annotations are made available as an object with array access capabilities.

Install via Composer

{
    "require": {
        "zeptech/annotations": "1.1.0"
    }
}

To instantiate simply pass a SPL Reflector instance with the getDocComment() method to the Annotations constructor.

<?php
use \zpt\anno\Annotations;

$classReflector = new ReflectionClass('MyClass');
$classAnnotations = new Annotations($classReflector);

$methodAnnotations = array();
foreach ($classReflector->getMethods() as $methodReflector) {
    $methodAnnotations[$methodReflector->getName()] = new Annotations($methodReflector);
}

Projects that create multiple Annotations instances for the same doc comment, or find it necessary to do a lot of argument passing to avoid this, may benefit from the use of an AnnotationFactory. AnnotationFactories will cache Annotation instances based on the doc comment's md5 hash value. Computing this value is generally faster than parsing the comment multiple times.

<?php
use \zpt\anno\AnnotationFactory;

$factory = new AnnotationFactory;
$annos = $factory->get('stdclass');

All annotations are case insensitive. The default value for all annotations is true.

<?php
/**
 * @Characteristic
 */
class MyClass {
}

$annotations = new Annotations(new ReflectionClass('MyClass'));
$annotations['Characteristic'] === true;

The absence of an annotation will result in a value of null:

$annotations['AnotherCharacteristic'] === null;
isset($annotations['AnotherCharacteristic']) === false;

The hasAnnotation($annotation) method can be used to determine the existance of an annotation, regardless of its value.

<?php
$annotations->hasAnnotation('Characteristic') === true;
$annotations->hasAnnotation('AnotherCharacteristic') === false;

A single annotation value can be defined as:

<?php
/**
 * @LikesToEat cheese
 */
class MyClass {
    // ...
}

$annotations['LikesToEat'] === 'cheese';

Some values will be cast into their expected types; strings 'true' and 'false' will be cast to their boolean equivalents and numeric values will be cast to either int or float types.

List values can be specified by providing a comma separated list surrounded with brackets:

<?php
/**
 * @LikesToEat [ cheese, kraft dinner, hot dogs ]
 */
// ...

$annotations['LikesToEat'] == array('cheese', 'kraft dinner', 'hot dogs');

A parsed list value will be represented as a PHP array:

<?php
is_array($annotations['LikesToEat']) === true

A map value can be specified using named parameters:

<?php
/**
 * @LikesToEat weekend = [ chips, dip ], anytime = [ cheese, kraft dinner, hot dogs ]
 */
// ...

$annotations['likesToEat']['weekend'] == array('chips', 'dip');
$annotations['likesToEat']['anytime'] == array('cheese', 'kraft dinner', 'hot dogs');

NOTE: It is possible at this time to nest list values inside of another list or to nest maps inside of another map or a list to use only json object start { and end with }.

@MenuData {"root":{"child":{"arraychild":[0,1,2,3]}},"arraysroot":[1,2,3]}

NOTE: All annotation values can be surrounded by optional parentheses.

<?php
/**
 * @LikesToEat([ cheese, kraft dinner, hot dogs ])
 * @DoesNotLikeToEat( morning = salad, night = [ toast, fruit ])
 */