type-lang / phpdoc
Library for recognizing PHPDoc annotations in PHP DocBlock comments
Installs: 9 016
Dependents: 4
Suggesters: 0
Security: 0
Stars: 6
Watchers: 1
Forks: 1
Open Issues: 0
Requires
- php: ^8.1
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.53
- jetbrains/phpstorm-attributes: ^1.0
- phpstan/extension-installer: ^1.3
- phpstan/phpstan: ^1.11
- phpstan/phpstan-strict-rules: ^1.6
- phpunit/phpunit: ^10.5|^11.0
- rector/rector: ^1.0
- type-lang/parser: ^1.0
This package is auto-updated.
Last update: 2024-10-29 09:48:27 UTC
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 aDescription
object.getTags()
― Provides a list ofTag
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 ofTag
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; }