Skip to content
This repository has been archived by the owner on Apr 12, 2024. It is now read-only.
/ annotation Public archive

Parsing PHPDoc style annotations from comments (Support PSR-5 DRAFT)

License

Notifications You must be signed in to change notification settings

panlatent/annotation

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

56 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Annotation

Build Status Latest Stable Version Total Downloads Latest Unstable Version License

Parsing PHPDoc style annotations from comments.

Annotation 是一个 PHPDoc 风格注释解析器,它能从注释里面解析 PHPDoc 注释元素并封装成对应的类。为了保证对 PHPDoc 注释解析的一致性, Annotation 遵循 PSR-5 PHPDoc草案。 与其他大多数库不同,它的解析器通过词法分析来解析 PHPDoc 。

它的目的是帮助用户轻松的获取 PHPDoc 注释中包含的信息。你可以使用它构建你的项目。使用继承关系特化标签或是创建自定义标签。

Usage

仅解析 PHPDoc

如果只需要解析 PHPDoc,仅需要构造解析器并调用 Parser::parser() 方法:

$docBlock = <<<DOC
/**
 * This is a phpdoc.
 */
DOC;

$parser = new Panlatent\Annotation\Parser();
$phpdoc = $parser->parser($docBlock);

echo $phpdoc->getSummary(); // Output: "This is a phpdoc."

解析 PHP 代码(使用反射)

$parser = new Panlatent\Annotation\Parser();
$annotation = new AnnotationClass(ExampleClass::class, $parser);

自定义标签

注册

自定义标签需要注册到 TagFactory 中,如果解析时发现未注册标签,将按照类似 PSR-4 的规则进行类查找。

$factory = new Panlatent\Annotation\TagFactory();
$factory->add('api', Panlatent\Annotation\Tag\ApiTag::class);
$parser = new Parser($factory);

或者

$parser = new Parser();
$factory = $parser->getTagFactory();
$factory->add('api', Panlatent\Annotation\Tag\ApiTag::class);

创建

创建一个类, 继承自 Panlatent\Annotation\Parser\Tag 或实现 Panlatent\Annotation\Parser\TagInterface,类名后缀为 Tag

例如,创建一个 \panlatent\annotation\add 标签, 类名为 Panlatent\Annotation\AddTag

/**
 * @\panlatent\annotation\add // 最前面的 '/' 不是必须的
 */

也可以创建一个别名,这需要你提前将别名注册,并绑定到一个类上:

/**
 * @add
 */

特化标签

特化标签形如 @api:restful ,推荐使用类的继承关系表示特化。特化标签与普通标签类明明规则相同。 例如,特化 @api 标签 @api:restful,对应类名为 ApiRestfulTag

/**
 * @api:restful post
 */

Parser

Annotation 的解析器由 4 个部分组成,包括预处理器、字符流生成器、词法分析器、语法分析器。

  • 预处理器是用来过滤包裹 PHPDoc * 符号或者无意义空白的工具。它可以将 * 替换为等效的空格,目的是保留原始字符串的未知 信息,也可以仅保留有效的PHPDoc。

  • 字符流生成器是用来生成字符流的类,专门针对字符流提供迭代器、预期和回溯操作、并提供字符的行号、列号和上下文信息。

  • 词法分析器会将字符流生成器送来的字符按照一定规则解析成 Token 。生成的 Token 以 yield (Generator PHP5.5+) 的方式输出, 并在必要的时候抛出异常。

  • 语法分析器从词法分析器中接受 Token 流,分析并生成语法树并组装成PHP类结构。

License

The Annotation is open-sourced software licensed under the MIT license.

About

Parsing PHPDoc style annotations from comments (Support PSR-5 DRAFT)

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages