minime/annotations

The KISS PHP annotations library

Tuesday, September 5, 2017
by marcioAlmada
Repository
13 Watchers
217 Stars
35,025 Installations

PHP
28 Dependents
0 Suggesters
23 Forks
6 Open issues
34 Versions
10 % Grown

The README.md

Minime \ Annotations

, _(*1)

Minime\Annotations is the first KISS PHP annotations library., _(*2)

Composer Installation

{
  "require": {
    "minime/annotations": "~3.0"
  }
}

Through terminal: composer require minime/annotations:~3.0 :8ball:, _(*3)

Setup

First grab an instance of the Minime\Annotations\Reader the lazy way:, _(*4)

$reader = \Minime\Annotations\Reader::createFromDefaults();

Or instantiate the annotations reader yourself with:, _(*5)

use Minime\Annotations\Reader;
use Minime\Annotations\Parser;
use Minime\Annotations\Cache\ArrayCache;

$reader = new Reader(new Parser, new ArrayCache);

Notice that Reader::createFromDefaults() creates a reader instance with array cache enabled. On production you might want to use a persistent cache handler like FileCache instead:, _(*6)

use Minime\Annotations\Cache\FileCache;

$reader->setCache(new FileCache('app/storage/path'));

Reading Annotations

Consider the following class with some docblock annotations:, _(*7)

<?php
/**
 * @name Foo
 * @accept ["json", "xml", "csv"]
 * @delta .60
 * @cache-duration 60
 */
class FooController
{
    /**
     * @manages Models\Baz
     */
    protected $repository;

    /**
     * @get @post
     * @redirect Controllers\BarController@index
     */
    public function index(){}
}

Let's use the Minime\Annotations\Reader instance to read annotations from classes, properties and methods. Like so:, _(*8)

$annotations = $reader->getClassAnnotations('FooController');

$annotations->get('name')     // > string(3) "Foo"
$annotations->get('accept')   // > array(3){ [0] => "json" [1] => "xml" [2] => "csv" }
$annotations->get('delta')           // > double(0.60)
$annotations->get('cache-duration')  // > int(60)

$annotations->get('undefined')  // > null

The same applies to class properties..., _(*9)

$annotations = $reader->getPropertyAnnotations('FooController', 'repository');
$annotations->get('manages')   // > string(10) "Models\Baz"

methods..., _(*10)

$annotations = $reader->getMethodAnnotations('FooController', 'index');
$annotations->get('get')   // > bool(true)
$annotations->get('post')   // > bool(true)
$annotations->get('auto-redirect')   // > string(19) "BarController@index"

and functions || closures:, _(*11)

/** @name Foo */ function foo(){}
$annotations = $reader->getFunctionAnnotations('foo');
$annotations->get('name')   // > string(3) "Foo"

Managing Annotations

The annotations reader Reader::get(*)Annotations always returns AnnotationsBag instances so you can easily manage annotations:, _(*12)

/**
 * @response.xml
 * @response.xls
 * @response.json
 * @response.csv
 * @method.get
 * @method.post
 */
class Foo {}

$annotations = $reader->getClassAnnotations('Foo'); // object<AnnotationsBag>

Namespacing

It's a good idea to namespace custom annotations that belong to a package. Later you can retrieve all those namespaced annotations using the AnnotationsBag api:, _(*13)

$AnnotationsBag->useNamespace('response')->toArray();
// > array(3){
// >    ["xml"]  => (bool) TRUE,
// >    ["xls"]  => (bool) TRUE,
// >    ["json"] => (bool) TRUE,
// >    ["csv"]  => (bool) TRUE
// > }

Piping Filters

You can also easily "pipe" filters. This time let's "grep" all annotations beginning with "x" and within "response" namespace:, _(*14)

$AnnotationsBag->useNamespace('response')->grep('/^x/')->toArray();
// > array(3){
// >    ["xml"]  => (bool) TRUE,
// >    ["xls"]  => (bool) TRUE
// > }

Traversing results

As you might expect, AnnotationsBag is traversable too:, _(*15)

foreach($annotations->useNamespace('method') as $annotation => $value)
{
    // some behavior
}

Union

You can also perform union operations between two annotations sets:, _(*16)

$annotations->union($defaultAnnotations);

Please refer to annotations bag public API for more operations., _(*17)

The Default Syntax

@(<namespace><namespace-delimiter>)?<annotation-identifier> <type>? <value>? , _(*18)

Which basically means that:, _(*19)

@ line must start with a docblock annotation tag
must have an annotation identifier
- annotation identifier can have namespace with segments delimited by . or \
whitespace
can have an annotation value
- value can have an optional type [json, string, integer, float, ->]
  - if absent, type is assumed from value
- whitespace
- optional value
  - if absent, true is assumed

Some valid examples below:, _(*20)

/**
 * Basic docblock showing syntax recognized by the default Minime\Annotations\Parser
 *
 * @implicit-boolean
 * @explicit-boolean true
 * @explicit-boolean false
 *
 * @implicit-string-annotation  hello world!
 * @explicit-string-annotation "hello world!"
 * @string-strong-typed-annotation string 123456
 *
 * @integer-annotation 15
 * @integer-strong-typed-annotation integer 15
 *
 * @float-annotation   0.15
 * @float-strong-typed float 15
 *
 * @json-annotation { "foo" : ["bar", "baz"] }
 * @strong-typed-json-annotation json ["I", "must", "be", "valid", "json"]
 * 
 * @namespaced.annotation hello!
 *
 * @multiline-json-annotation {
 *   "foo" : [
 *      "bar", "baz"
 *    ]
 * }
 *
 * @multiline-indented-string-annotation
 *   ------
 *   < moo >
 *   ------ 
 *         \   ^__^
 *          \  (oo)\_______
 *             (__)\       )\/\
 *                 ||----w |
 *                 ||     ||
 * 
 * @Concrete\Class\Based\Annotation -> { "foo" : ["bar"] }
 */

Concrete Annotations

Sometimes you need your annotations to encapsulate logic and you can only do it by mapping instructions to formal PHP classes. These kind of "concrete" typed annotations can be declared with the -> (arrow symbol):, _(*21)

/**
 * @Model\Field\Validation -> {
 *     "rules" : {
 *         "required" : true,
 *         "max-length" : 100
 *     }
 * }
 */

In the example above: when prompted, the annotation parser will instantiate a new \Model\Field\Validation() following the declared JSON prototype { "rules" : {...} }. Voilà! Instantly classy annotations., _(*22)

Caching

This package comes with two basic cache handlers. ArrayCache (for testing) and a very simple FileCache handler for persistence. Cache handlers can be set during Minime\Annotations\Reader instantiation:, _(*23)

use Minime\Annotations\Reader;
use Minime\Annotations\Parser;
use Minime\Annotations\Cache\FileCache;

$cacheHandler = new FileCache('storage/path');
$reader = new Reader(new Parser, $cacheHandler);

Or later with Reader::setCache():, _(*24)

$reader->setCache(new FileCache);

Public API

Minime\Annotations\Reader

::getClassAnnotations($subject)

Get all annotations from a given class:, _(*25)

$reader->getClassAnnotations('Full\Qualified\Class');

::getPropertyAnnotations($subject, $propertyName)

Get all annotations from a given class property:, _(*26)

$reader->getPropertyAnnotations('Full\Qualified\Class', 'propertyName');

::getMethodAnnotations($subject, $methodName)

Get all annotations from a given class method:, _(*27)

$reader->getMethodAnnotations('Full\Qualified\Class', 'methodName');

::getFunctionAnnotations($fn)

Get all annotations from a given full qualified function name or closure:, _(*28)

$reader->getFunctionAnnotations('utils\foo');

::getCache()

::setCache(CacheInterface $cache)

::getParser()

::setParser(ParserInterface $cache)

Minime\Annotations\AnnotationsBag

::grep($pattern)

Filters annotations using a valid regular expression and returns a new AnnotationBag with the matching results., _(*29)

::useNamespace($pattern)

Isolates a given namespace of annotations. Basically this method filters annotations by a namespace and returns a new AnnotationBag with simplified annotations identifiers., _(*30)

::union(AnnotationsBag $bag)

Performs union operation with a subject AnnotationBag:, _(*31)

$annotations->union($defaultAnnotations);

::toArray()

::get($key, $default = null)

::getAsArray($key)

::has($key)

::set($key, $value)

::count

Minime\Annotations\Cache\FileCache

::__construct($storagePath = null)

See example in context with Minime\Annotations\Reader:, _(*32)

use Minime\Annotations\Cache\FileCache;

$reader->setCache(new FileCache('app/tmp/storage/path'));

If no path is given OS tmp dir is assumed as cache storage path., _(*33)

::clear()

Clears entire cache. See example in context with Minime\Annotations\Reader:, _(*34)

$reader->getCache()->clear();

Minime\Annotations\Cache\ArrayCache

::clear()

Clears entire cache. See example in context with Minime\Annotations\Reader:, _(*35)

$reader->getCache()->clear();

Contributions

Found a bug? Have an improvement? Take a look at the issues., _(*36)

Guide

Fork minime\annotations
Clone forked repository
Install composer dependencies $ composer install
Run unit tests $ phpunit
Modify code: correct bug, implement features
Back to step 4

Copyright

The Versions

05/09 2017

dev-master

9999999-dev

The KISS PHP annotations library

library annotations

The KISS PHP annotations library

minime/annotations

The README.md

Minime \ Annotations

Composer Installation

Setup

Reading Annotations

Managing Annotations

Namespacing

Piping Filters

Traversing results

Union

The Default Syntax

Concrete Annotations

Caching

Public API

Minime\Annotations\Reader

::getClassAnnotations($subject)

::getPropertyAnnotations($subject, $propertyName)

::getMethodAnnotations($subject, $methodName)

::getFunctionAnnotations($fn)

::getCache()

::setCache(CacheInterface $cache)

::getParser()

::setParser(ParserInterface $cache)

Minime\Annotations\AnnotationsBag

::grep($pattern)

::useNamespace($pattern)

::union(AnnotationsBag $bag)

::toArray()

::get($key, $default = null)

::getAsArray($key)

::has($key)

::set($key, $value)

::count

Minime\Annotations\Cache\FileCache

::__construct($storagePath = null)

::clear()

Minime\Annotations\Cache\ArrayCache

::clear()

Contributions

Guide

Copyright

The Versions

dev-master

The Requires

The Development Requires

by Márcio Almada

3.1.0

The Requires

The Development Requires

by Márcio Almada

3.0.2

The Requires

The Development Requires

by Márcio Almada

3.0.1

The Requires

The Development Requires

by Márcio Almada

v3.x-dev

The Requires

The Development Requires

by Márcio Almada

3.0.0

The Requires

The Development Requires

by Márcio Almada

2.3.1

The Requires

The Development Requires

by Márcio Almada

2.x-dev

The Requires

The Development Requires

by Márcio Almada

2.3.0

The Requires

The Development Requires