README

Jasny PHPDoc 解析器

可配置的 DocBlock 解析器来自 PHP。

PHPDoc 解析器允许您配置标签，包括解析和提取信息的方法。这与 phpDocumentor 风格的注解相一致，与 Doctrine 类型注解不同。

安装

composer require jasny/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\Set\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' => "The description of foo. 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'
]

标签

以下标签包含在 PhpDocumentor::tags() 中

• @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

如果只需要解析这些标签，可以简单地做

use Jasny\PhpdocParser\PhpdocParser;
use Jasny\PhpdocParser\Set\PhpDocumentor;

//$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

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。

use Jasny\PhpdocParser\PhpdocParser;
use Jasny\PhpdocParser\Set\PhpDocumentor;
use phpDocumentor\Reflection\Types\ContextFactory;
use phpDocumentor\Reflection\FqsenResolver;

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

$contextFactory = new ContextFactory();
$context = $contextFactory->createFromReflector($reflection);

$resolver = new 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);