Download the PHP package zeptech/annotations without Composer

PHP Annotations

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

Install via Composer

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

Instantiation

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

Factory

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.

Annotation syntax

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

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

An annotation can be explicitely set to have the value false:

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

Annotation values

A single annotation value can be defined as:

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.

Lists

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

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

Lists can also be created by defining multiple annotations with the same name:

Maps

A map value can be specified using named parameters:

Nesting

Lists can nested inside of lists or maps.

At this time, this is only supported for one level of nesting. Deep nesting is not supported. Also, maps cannot be nested. If deep nesting or nested maps are required, values specified as JSON objects will be parsed using json_decode.

Because of the use of json_decode, the parsed value will be an instance of stdClass rather than an array:

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

Oddities

Mixing types when using multiple declarations will likely not cause an error but isn't officially supported and may have some weird behaviour. The final result will depend on the order of the types used.

Values can be enclosed in double quotes, which will be stripped, but this feature it isn't well supported and probably doesn't behave the way one might expect. This is something that might get proper handling in the future.

Also note that while annotation names are case insensitve, parameter names are case sensitive. This is a result of the top level annotations being stored in an object which implements custom accessors, but map values being stored as native array instances.

Contributing

Dev setup:

1. Install composer locally

   php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
   php -r "if (hash_file('sha384', 'composer-setup.php') === '906a84df04cea2aa72f40b5f787e49f22d4c2f19492ac310e8cba5b96ac8b64115ac402c8cd292b8a03482574915d1a8') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
   php composer-setup.php
   php -r "unlink('composer-setup.php');"

2. Install dependencies:

   php composer.phar update

3. Run Tests:

   ./vendor/bin/phpunit test