PHPDoc Parser for PHPStan

This library phpstan/phpdoc-parser represents PHPDocs with an AST (Abstract Syntax Tree). It supports parsing and modifying PHPDocs.

For the complete list of supported PHPDoc features check out PHPStan documentation. PHPStan is the main (but not the only) user of this library.

• PHPDoc Basics (list of PHPDoc tags)
• PHPDoc Types (list of PHPDoc types)
• phpdoc-parser API Reference with all the AST node types etc.

This parser also supports parsing Doctrine Annotations. The AST nodes live in the PHPStan\PhpDocParser\Ast\PhpDoc\Doctrine namespace.

Features

Supported type syntax

The parser supports a rich type system including:

• Basic types: string, int, bool, null, self, static, $this, etc.
• Nullable types: ?string
• Union and intersection types: string|int, Foo&Bar
• Generic types with variance: array<string>, Collection<covariant T>
• Array shapes: array{name: string, age: int, ...}
• Object shapes: object{name: string, age: int}
• Callable/closure types: callable(string): bool, Closure(int): void
• Conditional types: ($input is string ? string : int)
• Offset access types: T[K]
• Constant type expressions: self::CONST*, 123, 'string'

Constant expression parsing

Constant expressions used in PHPDoc tags are parsed via ConstExprParser:

• Scalar values: integers, floats, strings, true, false, null
• Arrays: {1, 2, 'key' => 'value'}
• Class constant fetches: ClassName::CONSTANT

AST node traversal

The library provides a visitor-based traversal system (inspired by nikic/PHP-Parser) for reading and transforming the AST.

usePHPStan\PhpDocParser\Ast\AbstractNodeVisitor;
usePHPStan\PhpDocParser\Ast\Node;
usePHPStan\PhpDocParser\Ast\NodeTraverser;
usePHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
$visitor = newclassextends AbstractNodeVisitor {
publicfunctionenterNode(Node$node) {
if ($nodeinstanceof IdentifierTypeNode) {
// inspect or transform the node
}
return$node;
}
};
$traverser = newNodeTraverser([$visitor]);
$traverser->traverse([$phpDocNode]);

The NodeTraverser supports DONT_TRAVERSE_CHILDREN, STOP_TRAVERSAL, REMOVE_NODE, and DONT_TRAVERSE_CURRENT_AND_CHILDREN control constants. A built-in CloningVisitor is included for creating deep copies of the AST (used by the format-preserving printer).

Node attributes

Nodes can carry attributes such as line numbers, token indexes, and comments. Enable them via ParserConfig:

$config = newParserConfig(usedAttributes: ['lines' => true, 'indexes' => true, 'comments' => true]);

These attributes are required for the format-preserving printer and can also be used for mapping AST nodes back to source positions.

Installation

composer require phpstan/phpdoc-parser

Basic usage

<?phprequire_once__DIR__ . '/vendor/autoload.php';
usePHPStan\PhpDocParser\Ast\PhpDoc\ParamTagValueNode;
usePHPStan\PhpDocParser\Ast\PhpDoc\PhpDocNode;
usePHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
usePHPStan\PhpDocParser\Lexer\Lexer;
usePHPStan\PhpDocParser\ParserConfig;
usePHPStan\PhpDocParser\Parser\ConstExprParser;
usePHPStan\PhpDocParser\Parser\PhpDocParser;
usePHPStan\PhpDocParser\Parser\TokenIterator;
usePHPStan\PhpDocParser\Parser\TypeParser;
// basic setup$config = newParserConfig(usedAttributes: []);
$lexer = newLexer($config);
$constExprParser = newConstExprParser($config);
$typeParser = newTypeParser($config, $constExprParser);
$phpDocParser = newPhpDocParser($config, $typeParser, $constExprParser);
// parsing and reading a PHPDoc string$tokens = newTokenIterator($lexer->tokenize('/** @param Lorem $a */'));
$phpDocNode = $phpDocParser->parse($tokens); // PhpDocNode$paramTags = $phpDocNode->getParamTagValues(); // ParamTagValueNode[]echo$paramTags[0]->parameterName; // '$a'echo$paramTags[0]->type; // IdentifierTypeNode - 'Lorem'

Format-preserving printer

This component can be used to modify the AST and print it again as close as possible to the original.

It's heavily inspired by format-preserving printer component in nikic/PHP-Parser.

<?phprequire_once__DIR__ . '/vendor/autoload.php';
usePHPStan\PhpDocParser\Ast\NodeTraverser;
usePHPStan\PhpDocParser\Ast\NodeVisitor\CloningVisitor;
usePHPStan\PhpDocParser\Ast\PhpDoc\PhpDocNode;
usePHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
usePHPStan\PhpDocParser\Lexer\Lexer;
usePHPStan\PhpDocParser\ParserConfig;
usePHPStan\PhpDocParser\Parser\ConstExprParser;
usePHPStan\PhpDocParser\Parser\PhpDocParser;
usePHPStan\PhpDocParser\Parser\TokenIterator;
usePHPStan\PhpDocParser\Parser\TypeParser;
usePHPStan\PhpDocParser\Printer\Printer;
// basic setup with enabled required lexer attributes$config = newParserConfig(usedAttributes: ['lines' => true, 'indexes' => true, 'comments' => true]);
$lexer = newLexer($config);
$constExprParser = newConstExprParser($config);
$typeParser = newTypeParser($config, $constExprParser);
$phpDocParser = newPhpDocParser($config, $typeParser, $constExprParser);
$tokens = newTokenIterator($lexer->tokenize('/** @param Lorem $a */'));
$phpDocNode = $phpDocParser->parse($tokens); // PhpDocNode$cloningTraverser = newNodeTraverser([newCloningVisitor()]);
/** @var PhpDocNode $newPhpDocNode */
[$newPhpDocNode] = $cloningTraverser->traverse([$phpDocNode]);
// change something in $newPhpDocNode$newPhpDocNode->getParamTagValues()[0]->type = newIdentifierTypeNode('Ipsum');
// print changed PHPDoc$printer = newPrinter();
$newPhpDoc = $printer->printFormatPreserving($newPhpDocNode, $phpDocNode, $tokens);
echo$newPhpDoc; // '/** @param Ipsum $a */'

Code of Conduct

This project adheres to a Contributor Code of Conduct. By participating in this project and its community, you are expected to uphold this code.

Building

Initially you need to run composer install, or composer update in case you aren't working in a folder which was built before.

Afterwards you can either run the whole build including linting and coding standards using

make

or run only tests using

make tests