phpstan/phpdoc-parser

In version 2.0, parser classes (like Lexer, ConstExprParser, TypeParser, and PhpDocParser) share a common ParserConfig object. This ensures consistent configuration across the parser components and allows for future optional parameters without breaking constructor signatures.

Instead of passing multiple boolean values and attribute arrays to each constructor, instantiate a ParserConfig and pass it to all parser components.

use PHPStan\PhpDocParser\Lexer\Lexer;
use PHPStan\PhpDocParser\ParserConfig;
use PHPStan\PhpDocParser\Parser\ConstExprParser;
use PHPStan\PhpDocParser\Parser\TypeParser;
use PHPStan\PhpDocParser\Parser\PhpDocParser;

$config = new ParserConfig(usedAttributes: ['lines' => true, 'indexes' => true]);
$lexer = new Lexer($config);
$constExprParser = new ConstExprParser($config);
$typeParser = new TypeParser($config, $constExprParser);
$phpDocParser = new PhpDocParser($config, $typeParser, $constExprParser);

To modify a PHPDoc while keeping the original formatting (comments, spacing, etc.), follow these steps:

1. Enable required attributes (lines, indexes, comments) in ParserConfig.
2. Use a NodeTraverser with a CloningVisitor to create a deep copy of the AST.
3. Modify the cloned AST nodes.
4. Use Printer::printFormatPreserving() passing the modified node, the original node, and the original tokens.

<?php

require_once __DIR__ . '/vendor/autoload.php';

use PHPStan\PhpDocParser\Ast\NodeTraverser;
use PHPStan\PhpDocParser\Ast\NodeVisitor\CloningVisitor;
use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocNode;
use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
use PHPStan\PhpDocParser\Lexer\Lexer;
use PHPStan\PhpDocParser\ParserConfig;
use PHPStan\PhpDocParser\Parser\ConstExprParser;
use PHPStan\PhpDocParser\Parser\PhpDocParser;
use PHPStan\PhpDocParser\Parser\TokenIterator;
use PHPStan\PhpDocParser\Parser\TypeParser;
use PHPStan\PhpDocParser\Printer\Printer;

// basic setup with enabled required lexer attributes

$config = new ParserConfig(usedAttributes: ['lines' => true, 'indexes' => true, 'comments' => true]);
$lexer = new Lexer($config);
$constExprParser = new ConstExprParser($config);
$typeParser = new TypeParser($config, $constExprParser);
$phpDocParser = new PhpDocParser($config, $typeParser, $constExprParser);

$tokens = new TokenIterator($lexer->tokenize('/** @param Lorem $a */'));
$phpDocNode = $phpDocParser->parse($tokens); // PhpDocNode

$cloningTraverser = new NodeTraverser([new CloningVisitor()]);

/** @var PhpDocNode $newPhpDocNode */
[$newPhpDocNode] = $cloningTraverser->traverse([$phpDocNode]);

// change something in $newPhpDocNode
$newPhpDocNode->getParamTagValues()[0]->type = new IdentifierTypeNode('Ipsum');

// print changed PHPDoc
$printer = new Printer();
$newPhpDoc = $printer->printFormatPreserving($newPhpDocNode, $phpDocNode, $tokens);
echo $newPhpDoc; // '/** @param Ipsum $a */'

When upgrading to version 2.0, note the following major changes:

• PHP Version: Requires PHP 7.4 or newer.
• Configuration: Parser classes no longer accept individual boolean/array parameters in constructors. They now use a shared ParserConfig object.
• Doctrine Support: The parser now supports Doctrine Annotations. AST nodes for these are located in the PHPStan\PhpDocParser\Ast\PhpDoc\Doctrine namespace.
• Stricter Parsing: Invalid PHPDoc syntax that was previously silently treated as a description (e.g., missing whitespace between a type and a description) will now result in an InvalidTagValueNode.
• AST Changes:
  • QuoteAwareConstExprStringNode is removed; use ConstExprStringNode instead.
  • ArrayShapeNode construction is now via static methods.
  • Text between tags is now consistently treated as part of the preceding tag's description.

To parse a PHPDoc string, you must set up a Lexer, ConstExprParser, TypeParser, and the main PhpDocParser. The PhpDocParser::parse() method accepts a TokenIterator and returns a PhpDocNode representing the Abstract Syntax Tree (AST).

<?php

require_once __DIR__ . '/vendor/autoload.php';

use PHPStan\PhpDocParser\Ast\PhpDoc\ParamTagValueNode;
use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocNode;
use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
use PHPStan\PhpDocParser\Lexer\Lexer;
use PHPStan\PhpDocParser\ParserConfig;
use PHPStan\PhpDocParser\Parser\ConstExprParser;
use PHPStan\PhpDocParser\Parser\PhpDocParser;
use PHPStan\PhpDocParser\Parser\TokenIterator;
use PHPStan\PhpDocParser\Parser\TypeParser;

// basic setup

$config = new ParserConfig(usedAttributes: []);
$lexer = new Lexer($config);
$constExprParser = new ConstExprParser($config);
$typeParser = new TypeParser($config, $constExprParser);
$phpDocParser = new PhpDocParser($config, $typeParser, $constExprParser);

// parsing and reading a PHPDoc string

$tokens = new TokenIterator($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'