Home

Awesome

<a href="https://github.com/php-type-language" target="_blank"> <img align="center" src="https://github.com/php-type-language/.github/blob/master/assets/dark.png?raw=true"> </a>
<p align="center"> <a href="https://packagist.org/packages/type-lang/phpdoc"><img src="https://poser.pugx.org/type-lang/phpdoc/require/php?style=for-the-badge" alt="PHP 8.1+"></a> <a href="https://packagist.org/packages/type-lang/phpdoc"><img src="https://poser.pugx.org/type-lang/phpdoc/version?style=for-the-badge" alt="Latest Stable Version"></a> <a href="https://packagist.org/packages/type-lang/phpdoc"><img src="https://poser.pugx.org/type-lang/phpdoc/v/unstable?style=for-the-badge" alt="Latest Unstable Version"></a> <a href="https://raw.githubusercontent.com/php-type-language/phpdoc/blob/master/LICENSE"><img src="https://poser.pugx.org/type-lang/phpdoc/license?style=for-the-badge" alt="License MIT"></a> </p> <p align="center"> <a href="https://github.com/php-type-language/phpdoc/actions"><img src="https://github.com/php-type-language/phpdoc/workflows/tests/badge.svg"></a> </p>

Reference implementation for TypeLang PHPDoc Parser.

Read documentation pages for more information.

Installation

TypeLang PHPDoc Parser is available as Composer repository and can be installed using the following command in a root of your project:

composer require type-lang/phpdoc

Quick Start

$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);

Expected Output:

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"
    }
  ]
}

Structural Elements

DocBlock

DocBlock is a representation of the comment object.

/**                                 |
 * Hello world                      | ← DocBlock's description.
 *                                  |
 * @param int $example              | ← DocBlock's tag #1.
 * @throws \Throwable Description   | ← DocBlock's tag #2.
 */                                 |
/** @template-implements \Traversable<array-key, Tag> */
class DocBlock implements \Traversable
{
    public function getDescription(): Description;
    
    /** @return list<Tag> */
    public function getTags(): array;
}

Description

Description is a representation of the description object which may contain other tags.

/**
               ↓↓↓↓↓↓↓↓↓↓↓                         | ← This is a nested tag of the description.
 * Hello world {@see some} and blah-blah-blah.     |
   ↑↑↑↑↑↑↑↑↑↑↑             ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑     | ← This is part of the template.
 */
/** @template-implements \Traversable<array-key, Tag> */
class Description implements \Traversable, \Stringable
{
    public function getTemplate(): string;

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

Tag

A Tag represents a name (ID) and its contents.

/**
    ↓↓↓↓↓↓                                 | ← This is a tag name.
 * @throws \Throwable An error occurred.   |
           ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑   | ← This is tag description.
 */
class Tag implements \Stringable
{
    public function getName(): string;

    public function getDescription(): ?Description;
}