Overview
PHPDoc
Most PHP code keeps part of its types in the docblock: a @param narrowing
array to list<User>, a @throws PHP has no syntax for, a @template
making a class generic. The PHPDoc component reads such a comment into a
description and a list of tags, each parsed by what the tag means. Types in
the tags are read by the TypeLang grammar.
Installation
Section titled “Installation”composer require type-lang/phpdocuse TypeLang\PhpDoc\DocBlockParser;
$parser = DocBlockParser::createDefault();
$block = $parser->parse(<<<'PHPDOC' /** * Sends a notification to the given recipient. * * @see Mailer::send() The underlying transport. * @return bool */ PHPDOC);
echo $block->description; // "Sends a notification to the given recipient.\n"echo count($block); // 2
foreach ($block as $tag) { echo $tag->name; // "see", "return"}Broken tags do not break the comment
Section titled “Broken tags do not break the comment”A tag whose body does not match its grammar is returned as an InvalidTag
with the reason, the tags around it are parsed as usual. An unknown tag is a
plain Tag.
$block = $parser->parse(<<<'PHPDOC' /** * @param int $wellFormed * @param not a valid type here $because */ PHPDOC);
$broken = $block[1]; // InvalidTagecho $broken->reason->getMessage();// Malformed "@param" tag, expected: <Type> <Variable> [ <Description> ]- Reading a comment: what a
DocBlock, its description and its tags hold. - Types from Reflection:
@param,@returnand@templateof a class and its methods. - Platforms: the tag sets of phpDocumentor, PHPStan, Psalm, Phan, PhpStorm and PHP CodeSniffer, and how to pick them.
- Custom tags: a tag of your own, from the grammar to the platform.
- Tag reference: every tag the parser knows, by platform.