Skip to content

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.

composer require type-lang/phpdoc
use 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"
}

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]; // InvalidTag
echo $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, @return and @template of 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.