README

为PHP提供简单快速的注释支持。

安装

将 codeburner/annotator 添加到您的 composer.json 文件中。

{
    "require": {
        "codeburner/annotator": "1.*"
    }
}

或通过cli

$ composer require codeburner/annotator

别忘了安装或更新composer并包含 vendor/autoload.php 文件。

目录

• 介绍
• 语法
• 注释类
• 过滤值
• 基本用法
• 实际应用

介绍

注释是一种元数据形式，提供关于程序的数据，但不是程序本身的一部分。注释不会直接影响其注释的代码的操作。它通常用于JAVA应用程序中，在PHP中，没有原生的注释实现，但有示例存在，如Doctrine ORM使用PHPDoc注释风格注释模型。

语法

注释需要以 @ 开头，并在文档块 /** 内。注释名称遵循PHP中变量的相同规则，它们的值可以是任何内容，但将被解析为字符串，annotator不会进行任何转换，数组必须以json格式写入。

/**
 * @EmptyAnnotation
 * @OneAnnotation 1
 * @ComplexAnnotation {"key1": "value1", "key2": ["value2-1", "value2-2"]}
 */

注释类

默认情况下，任何注释都是 Codeburner\Annotator\Annotation，但您可以添加逻辑来特别化注释。为此，您必须创建一个新的类，该类扩展了 Codeburner\Annotator\Annotation。注释名称将是完整的类名，但可能受到 use 和 namespace 语句的影响。

namespace Foo\Bar;

use Foo\FooAnnotation;
use Foo\Bar\BarAnnotation as AliasedAnnotation;

/**
 * @BarAnnotation -f
 * @FooAnnotation -f
 * @AliasedAnnotation -f
 */

BarAnnotation 是 Foo\Bar\BarAnnotation 类，FooAnnotation 是 Foo\FooAnnotation 类，而 AliasedAnnotation 是 Foo\Bar\BarAnnotation class。

注意：所有定义的注释都必须在使用时具有 -f 标志，这意味着它是一个文件并且可以具有过滤器。

过滤值

在定义注释的类时，参数可以通过实现方法 public function filter() 进行格式化或过滤。

class MyAnnotation extends Codeburner\Annotator\Annotation
{
	public function filter()
	{
		array_filter($this->arguments, 'strtoupper');
	}
}

基本用法

/**
 * @cook Crystals
 * @with {"local": "trailer", "clothes": ["apron", "briefs"]}
 */

class HeisenbergController
{

	/**
	 * @number 1000
	 */

	public function count()
	{

	}

}

$reflection = new Codeburner\Annotator\Reflection\ReflectionAnnotatedClass(HeisenbergController::class);

echo "I'll cook ", 
		$reflection->getMethod("count")->getAnnotation("number"), " ", 
		$reflection->getAnnotation("cook"), " in my ", 
		$reflection->getAnnotation("with")->getArgument("local"), " with wearing ",
		implode(", ", $reflection->getAnnotation("with")->getArgument("clothes"));

实际应用

例如，在控制器中仅使用注释在 codeburner 路由系统 中注册路由。

use Codeburner\Router\Annotations\RouteStrategyAnnotation as RouteStrategy;
use Codeburner\Router\Annotations\RoutePrefixAnnotation as RoutePrefix;
use Codeburner\Router\Annotations\RouteAnnotation as Route;

/**
 * @RouteStrategy -f \Codeburner\Router\Strategy\SimpleDispatchStrategy
 * @RoutePrefix -f /blog
 */

class ArticleController
{

	/**
	 * @Route -f /
	 */

	public function index()
	{

	}
}

在此代码中有三个注释，@RouteStrategy、@RoutePrefix 和 @Route。路由系统将读取这些注释并根据它们构建路由。