README

TypeLang PHPDoc解析器的参考实现。

阅读文档页面获取更多信息。

安装

TypeLang PHPDoc解析器以Composer仓库的形式提供，可以在项目的根目录中使用以下命令进行安装

composer require type-lang/phpdoc

快速入门

$parser = new \TypeLang\PHPDoc\Parser();
$result = $parser->parse(<<<'PHPDOC'
    /**
     * Example description {@see some} and blah-blah-blah.
     *
     * @Example\Annotation("foo")
     * @return array<non-empty-string, TypeStatement>
     * @throws \Throwable
     */
    PHPDOC);

var_dump($result);

预期输出

TypeLang\PHPDoc\DocBlock {
  -description: TypeLang\PHPDoc\Tag\Description\Description {
    -template: "Example description %1$s and blah-blah-blah."
    -tags: array:1 [
      0 => TypeLang\PHPDoc\Tag\Tag {
        #description: TypeLang\PHPDoc\Tag\Description\Description {
          -template: "some"
          -tags: []
        }
        #name: "see"
      }
    ]
  }
  -tags: array:3 [
    0 => TypeLang\PHPDoc\Tag\Tag {
      #description: TypeLang\PHPDoc\Tag\Description\Description {
        -template: "("foo")"
        -tags: []
      }
      #name: "Example\Annotation"
    }
    1 => TypeLang\PHPDoc\Tag\Tag {
      #description: TypeLang\PHPDoc\Tag\Description\Description {
        -template: "array<non-empty-string, TypeStatement>"
        -tags: []
      }
      #name: "return"
    }
    2 => TypeLang\PHPDoc\Tag\Tag {
      #description: TypeLang\PHPDoc\Tag\Description\Description {
        -template: "\Throwable"
        -tags: []
      }
      #name: "throws"
    }
  ]
}

结构元素

DocBlock

DocBlock是注释对象的表示。

/**                                 |
 * Hello world                      | ← DocBlock's description.
 *                                  |
 * @param int $example              | ← DocBlock's tag #1.
 * @throws \Throwable Description   | ← DocBlock's tag #2.
 */                                 |

• getDescription() —— 提供一个Description对象。
• getTags() —— 提供一个Tag对象的列表。

/** @template-implements \Traversable<array-key, Tag> */
class DocBlock implements \Traversable
{
    public function getDescription(): Description;
    
    /** @return list<Tag> */
    public function getTags(): array;
}

描述

描述是描述对象的表示，可能包含其他标签。

/**
               ↓↓↓↓↓↓↓↓↓↓↓                         | ← This is a nested tag of the description.
 * Hello world {@see some} and blah-blah-blah.     |
   ↑↑↑↑↑↑↑↑↑↑↑             ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑     | ← This is part of the template.
 */

• getTemplate() —— 提供一个格式化后的描述模板字符串。
• getTags() —— 提供一个Tag对象的列表。

/** @template-implements \Traversable<array-key, Tag> */
class Description implements \Traversable, \Stringable
{
    public function getTemplate(): string;

    /** @return list<Tag> */
    public function getTags(): array;
}

标签

标签代表一个名称（ID）及其内容。

/**
    ↓↓↓↓↓↓                                 | ← This is a tag name.
 * @throws \Throwable An error occurred.   |
           ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑   | ← This is tag description.
 */

• getName() —— 提供标签的名称（ID）。
• getDescription() —— 提供标签的可选描述。

class Tag implements \Stringable
{
    public function getName(): string;

    public function getDescription(): ?Description;
}