Annotations

Annotations

This page describes how annotations can be used in Stubbles. For details about the concept behind annotations see annotations which contains a general introduction into the topic. For more details how to use this in a programming language see Java annotations.

How to define an annotation

Annotations can be defined on every element that can get a docblock comment: functions, methods, classes and properties. Additionally it is possible to define annotations for parameters in the docblock comment of the function or method where the parameter is part of.

/**
 * Class to demonstrate how to define annotations
 *
 * @MyAnnotation
 */
class Foo
{
    /**
     * an example property
     *
     * @var  string
     * @AnnotationWithValues(bar='dummy', baz=42, required=true)
     */
    protected $bar;

    /**
     * another example property
     *
     * @var  string
     * @AnnotationWithOneValue("anotherDummy")
     */
    protected $baz;

    /**
     * an example method
     *
     * @param  int  $param  a parameter
     * @CastedAnnotation[MyAnnotation]
     * @ParamAnnotation{param}(key='value')
     */
    public function aMethod($param)
    {
        // some code here
    }
}

In the above example you can see five different ways of defining an annotation. However, you can combine these ways as you like. You may have a casted annotation with no, one or more values. But lets go through all defined annotations.

• @MyAnnotation This is an annotation without any value.
• @AnnotationWithValues(bar='dummy', baz=42, required=true) This annotation has two values with the parameters bar, baz and required. One is a string, the other is an integer, and the last a boolean.
• @AnnotationWithOneValue("anotherDummy") This annotation has only a single string value.
• @CastedAnnotation[MyAnnotation] A casted annotation can be used distinguish between a marker and a hint which concrete actions the annotation consuming class should do. The first name is the marker, and the name part in square brackets denotes the action to follow.
• @ParamAnnotation{param}(key='value') This annotation is a parameter annotation defined for the parameter $param of the method aMethod(). The name in the curly braces denotes the name of the parameter this annotation is for. Please be aware that this annotation is not available when retrieving it via ReflectionMethod::getAnnotation('ParamAnnotation'), this will result in a ReflectionException.

In contrast to other implementations it is not required to create a separate class for the annotation.

Parameter types

The parameters can be one of the following types:

• string: must be enclosed in single or double quotes, possible ways are foo="bar" and bar='Foo'

• null: foo=null sets the value of foo to null, it can be written as NULL as well.

• integer and float: are written like in PHP: foo=42, bar=1.34

• boolean: If you assign true or false to a paramter without enclosing it in quotes, it will be converted to a boolean value: foo=true,bar=false

• net\stubbles\lang\reflect\ReflectionClass: It is also possible to specify a class name as a parameter value: clazz=example\more\MyExample.class

• Constants: simply use foo=BAR_CONST. If BAR_CONST has been defined earlier as a constant than the result value of foo will be the value of the constant. If no constant is found the result value of foo will be BAR_CONST.

Get annotations

To get information about annotated elements use the Stubbles reflection classes:

$refClass = new net\stubbles\lang\reflect\ReflectionClass('Foo');
if ($refClass->hasAnnotation('MyAnnotation') == true) {
    var_dump($refClass->getAnnotation('MyAnnotation'));
}

$refProperty = $refClass->getProperty('bar');
if ($refProperty->hasAnnotation('AnnotationWithValues') == true) {
    var_dump($refProperty->getAnnotation('AnnotationWithValues'));
}

$refProperty = $refClass->getProperty('baz');
if ($refProperty->hasAnnotation('AnnotationWithValues') == true) {
    var_dump($refProperty->getAnnotation('AnnotationWithValues'));
}

$refMethod = $refClass->getMethod('aMethod');
if ($refMethod->hasAnnotation('CastedAnnotation') == true) {
    var_dump($refMethod->getAnnotation('CastedAnnotation'));
}

$refParameters = $refMethod->getParameters();
if (refParameters[0]->hasAnnotation('ParamAnnotation') == true) {
    var_dump($refParameters[0]->getAnnotation('ParamAnnotation'));
}

Read values from annotations

As seen above annotations can have values. If we take the @AnnotationWithValues from the class above this is how you can access them:

$annotation = $refClass->getProperty('bar')->getAnnotation('AnnotationWithValues');
echo $annotation->getBar(); // prints "dummy"
echo $annotation->bar; // prints "dummy"
echo $annotation->getValueByName('bar'); // prints "dummy"
if ($annotation->isRequired()) {
    echo 'Required!';
}

These are the possibilities:

• Boolean values can be retrieved using the method is followed by their name.
• Any other value types can be retrieved using the method get followed by their name, as property of the annotation class, or using the getValueByName() method. Please note that boolean values can also be retrieved using the get method syntax, but most times it just doesn't look that good: getRequired() has a different connotation than isRequired() from the point of view of the reader of your code.

In case the annotation has an unnamed value only it can be retrieved using $annotation->value or $annotation->getValue().

Using the method syntax with get has the advantage that a default value can be supplied which will be returned in case a value with this name is not set:

echo $annotation->getAwesomeness('Roland TB-303'); // prints "Roland TB-303"

The default value for the is method syntax is false.

If values are optional their existence can be checked: $annotation->hasValueByName('bar') returns true if a value with the name bar is set, and false otherwise.

Annotation cache

As parsing annotations is quite expensive Stubbles will cache annotations once they are read. This means if you change an annotation in your code it doesn't become effective immediately. You will have to clear the cache using vendor/bin/clearCache.

If you perform an update with Composer and you registered the scripts as defined in the Installation guide the cache will be cleared automatically.