README

安装它

使用composer composer require bulton-fr/annotation。

使用它

首先，系统需要解析您的类

$annotations = new \BultonFr\Annotation\Reader(myClass::class);
$annotations->parse();

并获得所有找到的注释，您有方法

• public function obtainClassAnnotList(): array
• public function obtainMethodsList(): Parser\AbstractManyParser
• public function obtainPropertiesList(): Parsers\AbstractManyParser
• public function obtainMethodAnnotList(string $methodName): array
• public function obtainPropertyAnnotList(string $propertyName): array

类 Parser\AbstractManyParser 实现了类 Iterator，所以您可以用 foreach 来使用它。每个项目都将是一个 Parser\AbstractParser 的实例。
要从 Parser\AbstractParser 类获取包含所有注释的数组（例如 obtain*AnnotList 返回的数组），您应该使用 getAnnotList() 方法。

obtain*AnnotList 返回的数组具有以下格式：Annotations\AbstractAnnotation[<int>][<string>]。

所以例如

/**
 * @Table(name="writing_list")
 * @Security(role="admin", fct="mySecurityCheck")
 * @AddEntity(ns="\BultonFr\Annotation\Test\Functional\Ref\Account")
 * @AddEntity(
 *  ns="\BultonFr\Annotation\Test\Functional\Ref\Category",
 *  alias="Ref\Category"
 * )
 */

注释列表将具有以下格式

array(3) {
    "Table" => array(1) {
        0 => object \BultonFr\Annotation\Test\Functional\Annotations\Table
    },
    "Security" => array(1) {
        0 => object \BultonFr\Annotation\Test\Functional\Annotations\Security
    },
    "AddEntity" => array(2) {
        0 => object \BultonFr\Annotation\Test\Functional\Annotations\AddEntity,
        1 => object \BultonFr\Annotation\Test\Functional\Annotations\AddEntity,
    }
}

所有注释对象

当解析器找到注释时，会实例化一个 Parsers\Annotations\Info 的实例，它将包含有关注释的所有信息。包括

• “名称”（紧随 @ 之后的部分）
• 值（名称之后的部分，已修剪）。
  • 属性 valueStr 包含字符串值（如 docblock 中的值），没有换行符。
  • 属性 values 是所有值的数组。
    如果 valueStr 包含属性/值格式，则属性将是数组键；否则，数组键将是数字。

使用此对象中的信息，会实例化一个新的对象。当声明注释时，类名是存在的。每次找到此注释时，都会实例化此类。
您将通过 obtain*AnnotList 方法获得的正是此对象（而不是 Info 对象）。

用于注释的类必须扩展 Annotations\AbstractAnnotation。在其中，您可以访问 Reader 和 Info 对象，可以检测键是否已声明并获得键的值。

您可以在许多示例中找到如何创建一个专门用于注释的新类

• 类 /src/Annotations/AddNS
• 在 /test/Functional/Annotations/ 中的所有类

导入命名空间

许多注释系统使用使用 use 关键字声明的类。我选择不使用它，主要是为了避免每次都读取磁盘。因此，您将使用的所有注释都需要“导入”。
要导入注释，有两个选择

• 在解析器中声明它
• 使用注释 @AddNS

要声明新的注释，您需要两样东西

• 每次找到此注释时将实例化的完整类名。
• 要使用的别名（默认为类名）

在解析器上声明命名空间

为此，我们在 ParserManager 上使用 addImportedNS 方法。

/**
 * Add a new imported namespace (obtain by AddNS or manually)
 *
 * @param string $name The class path (with ns) of the class which will be
 *  instancied when the annotation defined by $alias will be found.
 * @param string $alias The annotation key
 *
 * @return void
 */
public function addImportedNS(string $name, string $alias)

$annotations = new \BultonFr\Annotation\Reader(myClass::class);
$annotations->getParserManager()->addImportedNS(
    \myApp\myCustomAnnotation::class
    'CustomAnnot'
);
$annotations->parse();

现在，在 myClass（类、方法和属性 docblocks 中的注释）中，我可以使用注释 @CustomAnnot。

使用注释 AddNS

此注释只能添加到类 docblock 中。如果此注释存在于属性或方法中，则将不起作用。

/**
 * My class description
 *
 * @AddNS(ns="\myApp\myCustomAnnotation", alias="CustomAnnot")
 * @CustomAnnot(...)
 */
class myClass

当然，您可以直接使用导入的注解。当系统拥有所有 Info 对象时，它会首先读取所有 AddNS，然后读取其他所有注解（因此文档块的顺序并不重要）。

示例

$annotReader = new \BultonFr\Annotation\Reader(
    \BultonFr\Annotation\Test\Functional\Ref\Account
);

$annotReader
    ->getParserManager()
        ->addImportedNS('\BultonFr\Annotation\Test\Functional\Annotations\Column')
        ->addImportedNS('\BultonFr\Annotation\Test\Functional\Annotations\Route')
;

$annotReader->parse();

//string "int"
var_dump($annotReader->obtainPropertyAnnotList('id')['Column'][0]->getType());

忽略一个注解

有些注解会被系统忽略。例如，所有用于 docblock 的注解，如 @param 等。被忽略的注解列表在 Parsers\Annotations\Reader::ignoredAnnotations 中。
该列表基于 phpDocumentor 文档中的“标签参考”。
如果您在列表中看到缺少的注解，可以创建一个 issue 或 pull-request ;)

您可以使用 Parsers\Annotations\Reader::addIgnoredAnnotation 添加新的注解以忽略。

属性 ignoredAnnotations 和相关方法（获取器和添加）是静态的。因此，您需要为所有实例声明一次。

/**
 * Add a new annotation to ignore
 *
 * @param string $annotationName The annotation's name to ignore
 *  It's the part after the @.
 *
 * @return void
 */
public static function addIgnoredAnnotation(string $annotationName)