README

PhpDoc 解析器

PhpDoc 的轻量级解析器。

安装
- Composer
用法
标签
标签类
FQSEN 解析
当前限制
从原始版本修复

安装

PHP 7.1 及更高版本的安装

composer require rawr/phpdoc-parser

用法

/**
 * The description of foo. This function does a lot of thing
 *   which are described here.
 *
 * Some more text here.
 *
 * @important
 * @uses FooReader
 * @internal Why this isn't part of the API.
 *   Multi-line is supported.
 *
 * @param string|callable $first   This is the first param
 * @param int             $second  The second one
 * @return void
 * @throws InvalidArgumentException
 * @throws DoaminException if first argument is not found
 */
function foo($first, int $second)
{
   // ...
}

解析注解

use Jasny\PHPDocParser\PHPDocParser;
use Jasny\PhpdocParser\PhpDocumentor;
use Jasny\PHPDocParser\Tag\FlagTag;

$doc = (new ReflectionFunction('foo'))->getDocComment();

$customTags = [
    new FlagTag('important')
];
$tags = PhpDocumentor::tags()->with($customTags);

$parser = new PHPDocParser($tags);
$meta = $parser->parse($doc);

结果是以下内容

[
    'summery' => "The description of foo.",
    'description' => "This function does a lot of thing which are described here.\n\nSome more text.",
    'important' => true,
    'uses' => 'FooReader',
    'internal' => "Why this isn't part of the API. Mutlti-line is supported",
    'params' => [
        'first' => [
            'type' => "string|callable",
            'name' => "first",
            'description' => "This is the first parm"
        ],
        'second' => [
            'type' => "int",
            'name' => "second",
        ]
    ],
    'return' => 'void'
]

@api
@author
@copyright
@deprecated
@example
@ignore
@internal
@link
@method（所有方法将被分组到 methods 数组中）
@package
@param（所有参数将被分组到 params 数组中）
@property（所有属性将被分组到 properties 数组中）
@property-read（也包含在 properties 数组中）
@property-write（也包含在 properties 数组中）
@return
@see
@since
@throws（所有异常将被分组到 throws 数组中）
@todo
@uses
@used-by
@var

因此，如果您只需要解析这些标签，可以直接这样做

//$doc = ...; Get doc-comment string from reflection

$tags = PhpDocumentor::tags();
$parser = new PhpdocParser($tags);
$meta = $parser->parse($doc);

标签类

以下是一个包含可用标签类的列表，应该可以覆盖大多数用例

摘要
ArrayTag
CustomTag
DescriptionTag
ExampleTag
FlagTag
MapTag
MethodTag
ModifyTag
MultiTag
NumberTag
RegExpTag
VarTag
WordTag

以下函数用于标签文档中，用于简短地引用解析

function getNotations(string $doc, array $tags = []) {
    $tags = PhpDocumentor::tags()->add($tags);

    $parser = new PhpdocParser($tags);
    $notations = $parser->parse($doc);

    return $notations;
}

FQSEN 解析器

FQSEN 代表 Fully Qualified Structural Element Name（完全限定结构元素名称）。FQSEN 转换器用于将类名或函数名扩展为完全唯一的名称（包含完整的命名空间）。例如，Foo 可以转换为 Zoo\\Foo\\Bar。

此类库中使用了此类转换器。一些处理变量类型或类名的标签支持将它们作为构造函数参数添加。

例如，TypeTag，可以用于解析 @return 标签，具有以下构造函数：TypeTag($name, $fqsenConvertor = null)。如果提供，转换器将扩展文档注释中作为返回值类型的类型。如果省略，类型将保持与文档注释中相同。

转换器可以通过以下两种方式之一提供

$tags = PhpDocumentor::tags($fn) - 对于在 PhpDocumentor::tags() 中预定义的所有标签
$tags = $tags->add(new TypeTag('footag', $fn)) - 对于显式添加到预定义中的所有标签，它应该作为构造函数参数传递（如果构造函数支持）。

然后从标签创建解析器，$parser = new PhpdocParser($tags)。

解析函数应接受一个类名并返回一个扩展名称。

示例

此示例使用 phpDocumentor/TypeResolver。

$reflection = new ReflectionClass('\My\Example\Classy');

$contextFactory = new \phpDocumentor\Reflection\Types\ContextFactory();
$context = $contextFactory->createFromReflector($reflection);

$resolver = new \phpDocumentor\Reflection\FqsenResolver();
$fn = fn(string $class): string => $resolver->resolve($class, $context);

$tags = PhpDocumentor::tags($fn);
$parser = new PhpdocParser($tags);

$doc = $reflection->getDocComment();
$meta = $parser->parse($doc);

当前限制

某些标签尚不支持，例如 @license 或 @category。

不支持注解，例如

/**
 * @ORM\Entity(repositoryClass="MyProject\UserRepository")
 */

据我所知，此项目尚不支持解析内联标签
标签 @see 只解析一次，而不是所有出现
标签 @since 忽略描述
标签 @version 忽略描述
标签 @var 不允许忽略变量名
标签 @link 忽略描述
标签 @deprecated 忽略描述
CustomTag 扩展性不足，可能需要一个新的实现。

从原始版本修复

原始实现位于 https://github.com/jasny/phpdoc-parser。

到目前为止已修复和改进的功能

标签 @param 无法正确处理多行标签，现已修复。
将拼写错误 "summery" 修正为 "summary"。
不正确地解析了多行摘要。
添加了对 @version 标签的支持。
@method 正确解释了 static。
修复了不正确解析未关闭或关闭不正确的文档块的问题。
之前的解析器无法解析行结束符 CR 和 CRLF，现在它支持： LF、CR、CRLF。

rawr / phpdoc-parser

维护者

详细信息

README

PhpDoc 解析器

安装

用法

标签

标签类

FQSEN 解析器

示例

当前限制

从原始版本修复