type-lang/phpdoc

Library for recognizing PHPDoc annotations in PHP DocBlock comments

1.0.1 2025-01-11 00:11 UTC

Requires

• php: ^8.1

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.53
• jetbrains/phpstorm-attributes: ^1.0
• phpstan/phpstan: ^2.1
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^10.5|^11.0
• type-lang/parser: ^1.0

MIT

• phpdoc
• php
• dictionary
• language
• tags
• docblock

README

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;
}