README

描述

knot-lib/annotations是一个轻量级注解库。

特性

• 轻量级
• 最小PHPDoc注解支持
  • @package
  • @param
  • @throws
  • @return
  • @var
• 自定义注解（标记注解）
  • @Foo
• 自定义注解（单值注解）
  • @Foo("foo")
  • @Foo(3.14)
  • @Foo(Bar::VALUE)
• 自定义注解（单数组值注解）
  • @Foo({1, 2, 3})
• 自定义注解（完整注解）
  • @Foo(p1="foo",p2="bar")
• 自定义注解对象（您可以在运行时从注解包对象中获取注解对象）
• 自定义注解类（您可以实现自己的自定义注解类）

要求

PHP 7.2或更高版本

安装knot-lib/annotations

安装knot-lib/annotations的推荐方式是通过Composer。

composer require knot-lib/annotations

安装后，您需要要求Composer的自动加载器

require 'vendor/autoload.php';

示例

示例类：Person（注解类）

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;
    }
}

示例类：Apple（方法参数类）

namespace Food\Fruit;

class Apple
{
}

示例类：Taro（带有自定义注解的注解类）

namespace The\World;

use CustomAnnotation\Job;

/**
 * Class Taro
 * @package The\World
 * @Job(name="clerk", position="manager")
 */
class Taro extends Person
{
}

示例类：Job（自定义注解类）

namespace CustomAnnotation;

use knot-lib\Annotations\Annotation\FullAnnotation;

class Job extends FullAnnotation
{
}

读取器

use knot-libLib\Annotations\Parser\DefaultParser;
use knot-libLib\Annotations\AnnotationReader;
use The\World\Person;

$reader = new AnnotationReader(new DefaultParser());

类注解

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"
    }
}
*/

方法注解

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"
    }
}
*/

属性注解

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"
    }
}
*/

自定义注解对象

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

支持的标签（默认解析器）

类注解

• @package package_name

方法注解

• @param type varname
• @throws type
• @return type

属性注解

• @var type

自定义注解

• 标记注解：@AnnotationClass
• 单值注解：@AnnotationClass(value)
• 单数组值注释：@AnnotationClass({ value1, value2, ... })
• 完整注释：@AnnotationClass(param1="string", param2=3.14, ...)
• 支持字符串、布尔值、整数、浮点数（双精度）
• 支持类常量（Foo::VALUE）

需求

PHP 7.1 或更高版本

安装 knot-lib/annotations

安装knot-lib/annotations的推荐方式是通过Composer。

composer require knot-lib/annotations

安装后，您需要要求Composer的自动加载器

require 'vendor/autoload.php';

许可证

此库使用 MIT 许可证授权。

作者

stk2k

免责声明

本软件不提供任何保修。

我们不对此软件使用导致的结果负责。请自行承担责任。