knot-lib/annotations

Lightweight annotation library for kNot framework.

This package's canonical repository appears to be gone and the package has been frozen as a result.

0.3.0 2021-06-05 20:17 UTC

Requires

• php: >=7.2
• ext-json: *
• knot-lib/exception: ~0.1

Requires (Dev)

• mikey179/vfsstream: 1.3.*
• php-coveralls/php-coveralls: ^2.0
• phpunit/phpunit: ^8.5.15

MIT

• Katsuki Shuto

• php
• annotation

README

Description

knot-lib/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.2 or later

Installing knot-lib/annotations

The recommended way to install knot-lib/annotations is through Composer.

composer require knot-lib/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 knot-lib\Annotations\Annotation\FullAnnotation;

class Job extends FullAnnotation
{
}

Reader

use knot-libLib\Annotations\Parser\DefaultParser;
use knot-libLib\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

Requirement

PHP 7.1 or later

Installing knot-lib/annotations

The recommended way to install knot-lib/annotations is through Composer.

composer require knot-lib/annotations

After installing, you need to require Composer's autoloader:

require 'vendor/autoload.php';

License

This library is licensed under the MIT license.

Author

stk2k

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.