calgamo / annotations
Lightweight annotation library for calgamo framework.
Installs: 1 210
Dependents: 1
Suggesters: 0
Security: 0
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Requires
- php: >=7.1
- ext-json: *
- calgamo/exception: ~0.2
Requires (Dev)
- calgamo/test: ~0.1
- mikey179/vfsstream: 1.3.*
- php-coveralls/php-coveralls: ^2.0
- phpunit/phpunit: ^6.3.0
README
Description
Calgamo/annotations is lightweight annotations library.
Feature
- lightweight
- Minimum PHPDoc annotation support
- @package
- @param
- @throws
- @return
- @var
- custom annotations(marker annotation)
- @Foo
- custom annotations(single scalar value annotation)
- @Foo("foo")
- @Foo(3.14)
- @Foo(Bar::VALUE)
- custom annotations(single array value annotation)
- @Foo({1, 2, 3})
- custom annotations(full annotation)
- @Foo(p1="foo",p2="bar")
- custom annotation object(You can get annotation object from annotation bag object in runtime)
- custom annotation class(You can implement your own custom annotation class)
Requirement
PHP 7.1 or later
Installing calgamo/annotations
The recommended way to install calgamo/annotations is through Composer.
composer require calgamo/annotations
After installing, you need to require Composer's autoloader:
require 'vendor/autoload.php';
Demo
Example class: Person(Annotated Class)
namespace The\World; use Food\Fruit\Apple; use CustomAnnotation\Job; /** * @package The\World */ class Person { /** @var string */ private $name; /** * @param Apple $p * @param int $count * * @return int * * @throws RuntimeException */ public function eat(Apple $p, int $count) { return 1; } }
Example class: Apple(Method Paramter Class)
namespace Food\Fruit; class Apple { }
Example class: Taro(Annotated Class With Custom Annotation)
namespace The\World; use CustomAnnotation\Job; /** * Class Taro * @package The\World * @Job(name="clerk", position="manager") */ class Taro extends Person { }
Example class: Job(Custom Annotation Class)
namespace CustomAnnotation; use Calgamo\Annotations\Annotation\FullAnnotation; class Job extends FullAnnotation { }
Reader
use Calgamo\Annotations\Parser\DefaultParser; use Calgamo\Annotations\AnnotationReader; use The\World\Person; $reader = new AnnotationReader(new DefaultParser());
Class annotations
use The\World\Person; $bag = $reader->getClassAnnotations(new ReflectionClass(Person::class)); echo count($bag); // 1 echo json_encode($bag['@package']); // {"package_name":"The\\World"} foreach($bag as $tag => $params){ echo 'tag: ' . $tag . PHP_EOL; echo 'params: ' . json_encode($params) . PHP_EOL; } /* tag: @package params: {"package_name":"The\\World"} */ print_r(json_encode($bag, JSON_PRETTY_PRINT)); /* { "@package": { "package_name": "The\\World" } } */
Method annotations
use The\World\Person; $bag = $reader->getMethodAnnotations(new ReflectionMethod(Person::class, 'eat')); echo count($bag); // 3 echo json_encode($bag['@param']); // [{"type":"Food\\Fruit\\Apple","varname":"$p"},{"type":"int","varname":"$count"}] echo json_encode($bag['@return']); // {"type":"int"} echo json_encode($bag['@throws']); // {"type":"RuntimeException"} foreach($bag as $tag => $params){ echo 'tag: ' . $tag . PHP_EOL; echo 'params: ' . json_encode($params) . PHP_EOL; } /* tag: @param params: [{"type":"Food\\Fruit\\Apple","varname":"$p"},{"type":"int","varname":"$count"}] tag: @return params: {"type":"int"} tag: @throws params: {"type":"RuntimeException"} */ print_r(json_encode($bag, JSON_PRETTY_PRINT)); /* { "@param": [ { "type": "Food\\Fruit\\Apple", "varname": "$p" }, { "type": "int", "varname": "$count" } ], "@return": { "type": "int" }, "@throws": { "type": "RuntimeException" } } */
Property annotations
use The\World\Person; $bag = $reader->getPropertyAnnotations(new ReflectionProperty(Person::class, 'name')); echo count($bag); // 1 echo json_encode($bag['@var']); // {"type":"string"} foreach($bag as $tag => $params){ echo 'tag: ' . $tag . PHP_EOL; echo 'params: ' . json_encode($params) . PHP_EOL; } /* tag: @var params: {"type":"string"} */ print_r(json_encode($bag, JSON_PRETTY_PRINT)); /* { "@var": { "type": "string" } } */
Custom annotation object
use The\World\Taro; $bag = $reader->getClassAnnotations(new ReflectionClass(Taro::class)); echo json_encode($bag['@Job']); // {"name":"clerk","position":"manager"} $job = $bag->getCustomAnnotationObject('@Job'); echo print_r($job->getValues(), true); /* Array ( [name] => clerk [position] => manager ) */ echo$job['name']; // clerk echo$job['position']; // manager
Supported tags(DefaultParser)
Class annotations
- @package package_name
Method annotations
- @param type varname
- @throws type
- @return type
Property annotations
- @var type
Custom annotations
- Marker annotation: @AnnotationClass
- Single scalar value annotation: @AnnotationClass(value)
- Single array value annotation: @AnnotationClass({ value1, value2, ... })
- Full annotation: @AnnotationClass(param1="string", param2=3.14, ...)
- string, boolean, integer, float(double) values are supported
- class constant(Foo::VALUE) is supported
License
This library is licensed under the MIT license.
Author
Disclaimer
This software is no warranty.
We are not responsible for any results caused by the use of this software. Please use the responsibility of the your self.