Reference implementation for TypeLang PHPDoc Parser.
Read documentation pages for more information.
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-
@abstract- Declare any Element as abstract -
@api- Highlight Element as being part of the public API -
@author- TODO -
@category- Used to organize groups of packages together -
@copyright- Used to document the copyright information of any Element. -
@deprecated- TODO -
@example- TODO -
@extends- Allows to extend templated classes and interfaces -
@filesource- TODO -
@final- Declare any Element as final -
@global- TODO -
@ignore- Used to tell documentation systems that Element are not to be processed. -
@implements- Allows to extend templated interfaces -
@inheritdoc- TODO -
@inherits- An alias of@extendstag -
@internal- TODO -
@license- Used to indicate which license is applicable -
@link- Indicates a custom relation between the associated Element and a website, which is identified by an absolute URI -
@method- Allows a class to know which "magic" methods are callable -
@mixin- TODO -
@no-named-arguments- Indicates that argument names may be changed in the future. -
@package- Used to categorize Element(s) into logical subdivisions -
@override- Mention to see if the method is actually overriding a definition -
@param- Used to document a single argument of a function or method -
@param-closure-this- TODO -
@param-immediately-invoked-callable- TODO -
@param-later-invoked-callable- TODO -
@param-out- TODO -
@property- Used to declare which "magic" properties are supported -
@property-read- Used to declare which "magic" properties are supported for reading -
@property-write- Used to declare which "magic" properties are supported for writing -
@pure-unless-callable-is-impure- TODO -
@readonly- TODO -
@require-extends- TODO -
@require-implements- TODO -
@return- Used to document the return value of functions or methods -
@returns- An alias of@returntag -
@seal-methods- TODO -
@seal-properties- TODO -
@see- Indicates a reference from the associated Symbol(s) to a website or other Symbol(s) -
@since- TODO -
@source- TODO -
@subpackage- Used to categorize Element(s) into logical subdivisions -
@suppress- TODO -
@template- Allows classes (and class-like entries), functions and methods to declare a generic type parameter -
@template-contravariant- Allows classes (and class-like entries), functions and methods to declare a generic contravariant type parameter -
@template-covariant- Allows classes (and class-like entries), functions and methods to declare a generic covariant type parameter -
@template-extends- An alias of@extendstag -
@template-implements- An alias of@implementstag -
@template-use- Allows to extend templated traits -
@throw- An alias of@throwstag -
@throws- Used to indicate whether Element throw a specific type of\Throwable(exception or error) -
@todo- TODO -
@unused-param- TODO -
@use- An alias of@template-usetag -
@used-by- TODO -
@uses- TODO -
@var- Document the Type of the following Element -
@version- TODO
-
@psalm-allow-private-mutation- TODO -
@psalm-api- Vendor-specific@apialias -
@psalm-assert- TODO -
@psalm-assert-if-false- TODO -
@psalm-assert-if-true- TODO -
@psalm-assert-untainted- TODO -
@psalm-check-type- TODO -
@psalm-check-type-exact- TODO -
@psalm-consistent-constructor- TODO -
@psalm-consistent-templates- TODO -
@psalm-external-mutation-free- TODO -
@psalm-extends- Vendor-specific@extendsalias -
@psalm-flow- TODO -
@psalm-if-this-is- TODO -
@psalm-ignore-falsable-return- TODO -
@psalm-ignore-nullable-return- TODO -
@psalm-ignore-var- TODO -
@psalm-ignore-variable-method- TODO -
@psalm-ignore-variable-property- TODO -
@psalm-immutable- TODO -
@psalm-implements- Vendor-specific@implementsalias -
@psalm-import-type- TODO -
@psalm-inheritors- TODO -
@psalm-internal- TODO -
@psalm-method- Vendor-specific@methodalias -
@psalm-mutation-free- TODO -
@psalm-no-seal-methods- TODO -
@psalm-no-seal-properties- TODO -
@psalm-override-method-visibility- TODO -
@psalm-override-property-visibility- TODO -
@psalm-param- Vendor-specific@paramalias -
@psalm-param-out- TODO -
@psalm-property- Vendor-specific@propertyalias -
@psalm-property-read- Vendor-specific@property-readalias -
@psalm-property-write- Vendor-specific@property-writealias -
@psalm-pure- TODO -
@psalm-readonly- TODO -
@psalm-readonly-allow-private-mutation- TODO -
@psalm-require-extends- TODO -
@psalm-require-implements- TODO -
@psalm-return- Vendor-specific@returnalias -
@psalm-scope-this- TODO -
@psalm-seal-methods- TODO -
@psalm-seal-properties- TODO -
@psalm-self-out- TODO -
@psalm-stub-override- TODO -
@psalm-suppress- TODO -
@psalm-taint-escape- TODO -
@psalm-taint-sink- TODO -
@psalm-taint-source- TODO -
@psalm-taint-specialize- TODO -
@psalm-taint-unescape- TODO -
@psalm-template- Vendor-specific@templatealias -
@psalm-template-contravariant- Vendor-specific@template-contravariantalias -
@psalm-template-covariant- Vendor-specific@template-covariantalias -
@psalm-this-out- TODO -
@psalm-trace- TODO -
@psalm-type- TODO -
@psalm-use- Vendor-specific@usealias -
@psalm-var- Vendor-specific@varalias -
@psalm-variadic- TODO -
@psalm-yield- TODO
-
@phpstan-allow-private-mutation- TODO -
@phpstan-assert- TODO -
@phpstan-assert-if-false- TODO -
@phpstan-assert-if-true- TODO -
@phpstan-consistent-constructor- TODO -
@phpstan-extends- TODO -
@phpstan-ignore- TODO -
@phpstan-ignore-line- TODO -
@phpstan-ignore-next-line- TODO -
@phpstan-immutable- TODO -
@phpstan-implements- TODO -
@phpstan-import-type- TODO -
@phpstan-impure- TODO -
@phpstan-method- Vendor-specific@methodalias -
@phpstan-param- Vendor-specific@paramalias -
@phpstan-param-closure-this- TODO -
@phpstan-param-immediately-invoked-callable- TODO -
@phpstan-param-later-invoked-callable- TODO -
@phpstan-param-out- TODO -
@phpstan-property- Vendor-specific@propertyalias -
@phpstan-property-read- Vendor-specific@property-readalias -
@phpstan-property-write- Vendor-specific@property-writealias -
@phpstan-pure- TODO -
@phpstan-pure-unless-callable-is-impure- TODO -
@phpstan-readonly- TODO -
@phpstan-readonly-allow-private-mutation- TODO -
@phpstan-require-extends- TODO -
@phpstan-require-implements- TODO -
@phpstan-return- Vendor-specific@returnalias -
@phpstan-self-out- TODO -
@phpstan-template- Vendor-specific@templatealias -
@phpstan-template-contravariant- Vendor-specific@template-contravariantalias -
@phpstan-template-covariant- Vendor-specific@template-covariantalias -
@phpstan-this-out- TODO -
@phpstan-throws- Vendor-specific@throwsalias -
@phpstan-type- TODO -
@phpstan-use- TODO -
@phpstan-var- Vendor-specific@varalias
-
@phan-abstract- Vendor-specific@abstractalias -
@phan-assert- TODO -
@phan-assert-false-condition- TODO -
@phan-assert-if-false- TODO -
@phan-assert-if-true- TODO -
@phan-assert-true-condition- TODO -
@phan-closure-scope- TODO -
@phan-constructor-used-for-side-effects- TODO -
@phan-extends- Vendor-specific@extendsalias -
@phan-file-suppress- TODO -
@phan-forbid-undeclared-magic-methods- TODO -
@phan-forbid-undeclared-magic-properties- TODO -
@phan-hardcode-return-type- TODO -
@phan-immutable- TODO -
@phan-inherits- Vendor-specific@extendsalias -
@phan-method- Vendor-specific@methodalias -
@phan-mixin- TODO -
@phan-output-reference- TODO -
@phan-override- Vendor-specific@overridealias -
@phan-param- Vendor-specific@paramalias -
@phan-property- Vendor-specific@propertyalias -
@phan-property-read- Vendor-specific@property-readalias -
@phan-property-write- Vendor-specific@property-writealias -
@phan-pure- TODO -
@phan-read-only- TODO -
@phan-real-return- TODO -
@phan-return- Vendor-specific@returnalias -
@phan-side-effect-free- TODO -
@phan-suppress-current-line- TODO -
@phan-suppress-next-line- TODO -
@phan-suppress-next-next-line- TODO -
@phan-suppress-previous-line- TODO -
@phan-template- Vendor-specific@templatealias -
@phan-transient- TODO -
@phan-type- TODO -
@phan-unused-param- TODO -
@phan-var- Vendor-specific@varalias -
@phan-write-only- TODO -
@phanclosurescope- TODO
$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\DocBlock {
+description: TypeLang\PHPDoc\DocBlock\Description\TaggedDescription {
+components: array:3 [
0 => TypeLang\PHPDoc\DocBlock\Description\Description {
#value: "Example description "
}
1 => TypeLang\PHPDoc\DocBlock\Tag\SeeTag\SeeTag {
+description: null
+name: "see"
+ref: TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\TypeSymbolReference {
+type: TypeLang\Parser\Node\Stmt\NamedTypeNode { … }
}
}
2 => TypeLang\PHPDoc\DocBlock\Description\Description {
#value: " and blah-blah-blah.\n"
}
]
}
+tags: array:3 [
0 => TypeLang\PHPDoc\DocBlock\Tag\Tag {
+description: TypeLang\PHPDoc\DocBlock\Description\Description {
#value: "("foo")\n"
}
+name: "Example\Annotation"
}
1 => TypeLang\PHPDoc\DocBlock\Tag\ReturnTag\ReturnTag {
+description: null
+name: "return"
+type: TypeLang\Parser\Node\Stmt\NamedTypeNode { … }
}
2 => TypeLang\PHPDoc\DocBlock\Tag\ThrowsTag\ThrowsTag {
+description: null
+name: "throws"
+type: TypeLang\Parser\Node\Stmt\NamedTypeNode { … }
}
]
}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.
*/ |$description― Provides aDescriptionobject.$tags― Provides a list ofTagobjects.
/**
* DocBlock structure pseudocode (real impl may differ)
*
* @template-implements \Traversable<array-key, Tag>
* @template-implements \ArrayAccess<array-key, Tag>
*/
class DocBlock
{
public ?Description $description { get; }
public iterable<array-key, Tag> $tags { get; }
}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.
*/$tags― Provides a list ofTagobjects.$components― Provides a list ofTag|Descriptionobjects.
/**
* Simple description structure pseudocode (real impl may differ)
*/
class Description implements \Stringable {}
/**
* Tagged (composite) description structure pseudocode (real impl may differ)
*
* @template-implements \Traversable<array-key, Tag>
* @template-implements \ArrayAccess<array-key, Tag>
*/
class TaggedDescription extends Description implements
\Traversable,
\ArrayAccess,
\Countable
{
public iterable<array-key, Tag> $tags { get; }
public iterable<array-key, Tag|Description> $components { get; }
}Tag
A Tag represents a name (ID) and its contents.
/**
↓↓↓↓↓↓ | ← This is a tag name.
* @throws \Throwable An error occurred. |
↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑ | ← This is tag description.
*/$name― Provides a tag's name (ID).$description― Provides an optional description of the tag.
/**
* Common tag structure pseudocode (real impl may differ)
*/
class Tag implements \Stringable
{
public non-empty-string $name { get; }
public ?Description $description { get; }
}
/**
* Throws tag structure pseudocode (real impl may differ)
*/
class ThrowsTag extends Tag
{
public TypeStatement $type;
}