---

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.
 */                                 |

• getDescription() ― Provides a Description object.
• getTags() ― Provides a list of Tag objects.

/** @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.
 */

• getTemplate() ― Provides a sprintf-formatted template string of the description.
• getTags() ― Provides a list of Tag objects.

/** @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.
 */

• getName() ― Provides a tag's name (ID).
• getDescription() ― Provides an optional description of the tag.

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

    public function getDescription(): ?Description;
}