PHPDoc Parser

https://github.com/phpstan/phpdoc-parser
Admin
A library for parsing and modifying PHPDocs with an Abstract Syntax Tree (AST), also supporting...
Tokens:96,320
Snippets:630
Trust Score:9.6
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install grammar toolchain with make grammars-install

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/README.md

Installs the grammar toolchain, which requires PHP 8.4. Without it, the fuzzy tests skip themselves.

```bash
make grammars-install   # install it
```

--------------------------------

### Install phpstan/phpdoc-parser with Composer

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/README.md

Install the phpstan/phpdoc-parser package via Composer.

```bash
composer require phpstan/phpdoc-parser
```

--------------------------------

### Basic PHPDoc Parsing

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/PhpDocParser.md

Demonstrates the setup of the Lexer, TypeParser, and PhpDocParser to parse a simple PHPDoc string and retrieve tag values.

```php
use PHPStan\\'PhpDocParser\\Ast\\PhpDoc\\ParamTagValueNode;\nuse PHPStan\\PhpDocParser\\Lexer\\Lexer;\nuse PHPStan\\PhpDocParser\\ParserConfig;\nuse PHPStan\\PhpDocParser\\Parser\\ConstExprParser;\nuse PHPStan\\PhpDocParser\\Parser\\PhpDocParser;\nuse PHPStan\\PhpDocParser\\Parser\\TokenIterator;\nuse PHPStan\\PhpDocParser\\Parser\\TypeParser;\n\n$config = new ParserConfig(usedAttributes: []);\n$lexer = new Lexer($config);\n$constExprParser = new ConstExprParser($config);\n$typeParser = new TypeParser($config, $constExprParser);\n$phpDocParser = new PhpDocParser($config, $typeParser, $constExprParser);\n\n$tokens = new TokenIterator($lexer->tokenize('/** @param Lorem $a */'));\n$phpDocNode = $phpDocParser->parse($tokens); // PhpDocNode\n$paramTags = $phpDocNode->getParamTagValues(); // ParamTagValueNode[]\n// $paramTags[0]->parameterName === '$a'\n// $paramTags[0]->type          === IdentifierTypeNode('Lorem')
```

--------------------------------

### Format-preserving ParserConfig setup

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/ParserConfig.md

Format-preserving setup enabling all three attribute groups ('lines', 'indexes', 'comments') so nodes carry source positions and comments for the printer. The conditional checks that line and index attributes are enabled before mapping nodes back to source positions.

```php
use PHPStan\PhpDocParser\ParserConfig;

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

if ($config->useLinesAttributes && $config->useIndexAttributes) {
    // nodes can be mapped back to source positions and re-printed
}
```

--------------------------------

### After: Constructor setup with ParserConfig

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/UPGRADING.md

Shows the new way of configuring parser classes using a shared ParserConfig object. This ensures consistent configuration and allows future optional parameters.

```php
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);
```

--------------------------------

### Basic ParserConfig usage

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/ParserConfig.md

Basic setup with no attributes. Creates a ParserConfig with an empty array and passes it to the Lexer, ConstExprParser, TypeParser, and PhpDocParser constructors.

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

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

--------------------------------

### ConstFetchNode usage example

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/ConstExprNodes.md

Shows how to instantiate ConstFetchNode with a wildcard constant name and echo it, producing 'self::CONST*'.

```php
use PHPStan\PhpDocParser\Ast\ConstExpr\ConstFetchNode;

$fetch = new ConstFetchNode('self', 'CONST*');
echo $fetch; // 'self::CONST*'
```

--------------------------------

### ArrayShapeNode

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/TypeNodes-Advanced.md

Documentation for the ArrayShapeNode class, including its constants, static factories, properties, and usage example.

```APIDOC
## ArrayShapeNode

### Description
Represents `array{...}`, `list{...}`, `non-empty-array{...}`, and `non-empty-list{...}` type nodes in PHPDoc. The constructor is private; use the static factories to create instances.

### Class
`PHPStan\PhpDocParser\Ast\Type\ArrayShapeNode`

### Constants
- `KIND_ARRAY` = `'array'`
- `KIND_LIST` = `'list'`
- `KIND_NON_EMPTY_ARRAY` = `'non-empty-array'`
- `KIND_NON_EMPTY_LIST` = `'non-empty-list'`

### Static Factories

#### `createSealed(array $items, string $kind = self::KIND_ARRAY): self`
Creates a sealed array shape node.

**Parameters**
- `$items` (ArrayShapeItemNode[]) - Required - Typed entries (keyed or positional).
- `$kind` (string) - Optional - One of the KIND_* constants. Defaults to `KIND_ARRAY`.

**Returns**
- `self` - A new ArrayShapeNode with `sealed = true` and `unsealedType = null`.

#### `createUnsealed(array $items, ?ArrayShapeUnsealedTypeNode $unsealedType, string $kind = self::KIND_ARRAY): self`
Creates an unsealed array shape node.

**Parameters**
- `$items` (ArrayShapeItemNode[]) - Required - Typed entries (keyed or positional).
- `$unsealedType` (?ArrayShapeUnsealedTypeNode) - Required - The rest type for the unsealed shape.
- `$kind` (string) - Optional - One of the KIND_* constants. Defaults to `KIND_ARRAY`.

**Returns**
- `self` - A new ArrayShapeNode with `sealed = false` and the given `unsealedType`.

### Properties
- `$items` (ArrayShapeItemNode[]) - Typed entries (keyed or positional).
- `$sealed` (bool) - `false` when `...` was written.
- `$kind` (self::KIND_*) - Which shape keyword started it.
- `$unsealedType` (?ArrayShapeUnsealedTypeNode) - The `...<...>` rest type when unsealed, else `null`.

### Example
```php
use PHPStan\PhpDocParser\Ast\Type\ArrayShapeNode;

// '/** @return array{name: string, age: int, ...<int, string>} */'
$shape = $phpDocNode->getReturnTagValues()[0]->type; // ArrayShapeNode
echo $shape->kind;              // 'array'
echo $shape->sealed;            // false
echo $shape->unsealedType;      // ArrayShapeUnsealedTypeNode(<int, string>)
echo count($shape->items);      // 2
```
```

--------------------------------

### PhpDocParser Usage

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/PhpDocParser.md

Code examples for basic parsing and error recovery using the PhpDocParser.

```APIDOC
## Basic Parse

### Description
Parses a PHPDoc comment into an AST (PhpDocNode) using the PhpDocParser.

### Usage
```php
use PHPStan\PhpDocParser\Ast\PhpDoc\ParamTagValueNode;
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;

$config = new ParserConfig(usedAttributes: []);
$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
$paramTags = $phpDocNode->getParamTagValues(); // ParamTagValueNode[]
// $paramTags[0]->parameterName === '$a'
// $paramTags[0]->type          === IdentifierTypeNode('Lorem')
```

### Parameters
- `$tokens` (TokenIterator) - Required - Token iterator created from the lexer output.

### Returns
- `PhpDocNode` - The parsed PHPDoc AST.

### Notes
- The `parse` method may throw `LogicException` if comments are not flushed properly.
- Invalid syntax does not throw; it produces an `InvalidTagValueNode` (see Error Recovery).
```

```APIDOC
## Error Recovery

### Description
Demonstrates how invalid PHPDoc syntax is handled: it does not throw, but produces an `InvalidTagValueNode` that can be inspected.

### Usage
```php
$tokens = new TokenIterator($lexer->tokenize('/** @return array{foo: int}} */'));
$phpDocNode = $phpDocParser->parse($tokens);

$returnTags = $phpDocNode->getReturnTagValues(); // [] — the tag value is invalid

$tags = $phpDocNode->getTagsByName('@return');
$value = $tags[0]->value; // InvalidTagValueNode
if ($value instanceof PHPStan\PhpDocParser\Ast\PhpDoc\InvalidTagValueNode) {
    $exception = $value->exception; // magic property, rebuilds ParserException
    echo $exception->getExpectedTokenType();
}
```

### Notes
- `InvalidTagValueNode::exception` is a magic property that lazily rebuilds the `ParserException`.
- The `parse` method may fabricate a `PhpDocNode` with an `InvalidTagValueNode` if the closing token cannot be consumed.
```

--------------------------------

### Attribute Usage

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/Ast-Node.md

Examples of reading and setting attributes on PHPDoc nodes, including source position attributes.

```APIDOC
## Attribute Usage

### Description
Examples of reading and setting attributes on PHPDoc nodes, including source position attributes.

### Reading Attributes
```php
use PHPStan\PhpDocParser\Ast\Attribute;
use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocNode;

$config = new ParserConfig(usedAttributes: ['lines' => true, 'indexes' => true]);
// ... parse a PHPDoc ...
/** @var PhpDocNode $phpDocNode */

$tag = $phpDocNode->getTags()[0];
echo $tag->getAttribute(Attribute::START_LINE);  // int or null
echo $tag->getAttribute(Attribute::END_INDEX);   // int or null
echo $tag->hasAttribute(Attribute::START_INDEX); // bool
```

### Setting/Unsetting Attributes
```php
$tag->setAttribute('myKey', ['anything' => true]);
$tag->setAttribute(Attribute::START_LINE, null); // unsets startLine
```
```

--------------------------------

### Parse a PHPDoc string with PhpDocParser

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/README.md

Set up the parser components (ParserConfig, Lexer, ConstExprParser, TypeParser, PhpDocParser) and parse a PHPDoc string. The example reads the parameter name and type from the parsed ParamTagValueNode.

```php
<?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'
```

--------------------------------

### Before: Constructor setup with separate arrays and booleans

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/UPGRADING.md

Shows the old way of configuring parser classes with separate boolean values and an attributes array. This approach is replaced by the ParserConfig object in version 2.0.

```php
use PHPStan\PhpDocParser\Lexer\Lexer;
use PHPStan\PhpDocParser\Parser\ConstExprParser;
use PHPStan\PhpDocParser\Parser\TypeParser;
use PHPStan\PhpDocParser\Parser\PhpDocParser;

$usedAttributes = ['lines' => true, 'indexes' => true];

$lexer = new Lexer();
$constExprParser = new ConstExprParser(true, true, $usedAttributes);
$typeParser = new TypeParser($constExprParser, true, $usedAttributes);
$phpDocParser = new PhpDocParser($typeParser, $constExprParser, true, true, $usedAttributes);
```

--------------------------------

### Usage example of ConstExprStringNode

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/ConstExprNodes.md

Shows how to create a ConstExprStringNode with a single-quoted string, access its unescaped value, and convert it back to a re-escaped string.

```php
use PHPStan\PhpDocParser\Ast\ConstExpr\ConstExprStringNode;

// '/** @param 'a b' $s */' → ConstTypeNode wrapping this node
$s = new ConstExprStringNode("a\tb", ConstExprStringNode::SINGLE_QUOTED);
echo $s->value;      // "a\tb" — already unescaped
echo (string) $s;    // "'a\tb'" — re-escaped for output
```

--------------------------------

### Using getTypelessParamTagValues()

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/PhpDocTagValues-Parameters.md

Shows how to retrieve typeless param tag values and access the parameterName property. The example uses a doc comment '/** @param $a hello */' and outputs '$a'.

```php
// '/** @param $a hello */'
$values = $phpDocNode->getTypelessParamTagValues();
echo $values[0]->parameterName; // '$a'
```

--------------------------------

### Access method tag values with templates and defaults

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/PhpDocTagValues-MethodTemplate.md

Shows how to access method tag values with templates and defaults. The parsed docblock is '/** @method static Foo<T> bar(T $x = 1, int ...$rest): Baz desc */'. The example prints the static flag, method name, return type, template types, and parameter details including default value and variadic flag.

```php
use PHPStan\PhpDocParser\Ast\PhpDoc\MethodTagValueNode;

// Parse: '/** @method static Foo<T> bar(T $x = 1, int ...$rest): Baz desc */'
$methods = $phpDocNode->getMethodTagValues();
/** @var MethodTagValueNode $method */
$method = $methods[0];
echo $method->isStatic;   // true
echo $method->methodName; // 'bar'
echo $method->returnType; // IdentifierTypeNode('Foo')
echo count($method->templateTypes); // 1 (TemplateTagValueNode 'T')
$param = $method->parameters[0];
echo $param->parameterName;   // '$x'
echo $param->defaultValue;    // ConstExprIntegerNode('1')
echo $param->isVariadic;      // false
echo $method->parameters[1]->isVariadic; // true
```

--------------------------------

### Read assert property and method tag values

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/PhpDocTagValues-MethodTemplate.md

Shows how to read assert variants. Property and method asserts are separate node classes, so you must check each collection separately. The example prints the property or method name from the first assert tag if present.

```php
if (count($phpDocNode->getAssertPropertyTagValues()) > 0) {
    echo $phpDocNode->getAssertPropertyTagValues()[0]->property;
}
if (count($phpDocNode->getAssertMethodTagValues()) > 0) {
    echo $phpDocNode->getAssertMethodTagValues()[0]->method;
}
```

--------------------------------

### TokenIterator class signature and constructor

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/TokenIterator.md

Class signature and constructor of TokenIterator. The constructor accepts a list of token triples from Lexer::tokenize() and an optional start index, then calls skipIrrelevantTokens() to skip horizontal whitespace.

```php
class TokenIterator
{

	/** @var list<array{string, int, int}> */
	private array $tokens;

	private int $index;

	/** @var list<Comment> */
	private array $comments = [];

	/** @var list<array{int, list<Comment>}> */
	private array $savePoints = [];

	/** @var list<int> */
	private array $skippedTokenTypes = [Lexer::TOKEN_HORIZONTAL_WS];

	private ?string $newline = null;

	/** @var list<int>|null */
	private ?array $offsets = null;

	/**
	 * @param list<array{string, int, int}> $tokens
	 */
	public function __construct(array $tokens, int $index = 0)
	{
		$this->tokens = $tokens;
		$this->index = $index;

		$this->skipIrrelevantTokens();
	}
	...
}
```

--------------------------------

### Modify and print PHPDoc with format-preserving Printer

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/README.md

Use the format-preserving printer to modify the AST and print it back close to the original. Requires enabling 'lines', 'indexes', and 'comments' lexer attributes in ParserConfig. The example clones the AST, changes the parameter type to 'Ipsum', and prints the modified PHPDoc.

```php
<?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 */'
```

--------------------------------

### Run full build with make

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/README.md

Runs the whole build including linting and coding standards.

```bash
make
```

--------------------------------

### Run all quality checks with make check

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/CLAUDE.md

Runs all quality checks: lint, code style, tests, and PHPStan. Use this comprehensive check before committing.

```bash
make check
```

--------------------------------

### Constructor

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/ConstExprParser.md

Creates a new ConstExprParser instance with the given configuration.

```APIDOC
## Constructor

### Description
Creates a new ConstExprParser instance with the given configuration.

### Method
Constructor

### Signature
```php
public function __construct(ParserConfig $config)
```

### Parameters
- **$config** (ParserConfig) - Required - Shared options.

### Returns
- A new ConstExprParser instance.
```

--------------------------------

### ParserConfig instantiation with named args and plain array

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/configuration.md

Two ways to instantiate ParserConfig: using named arguments (PHP 8+) or a plain associative array. Unknown keys are ignored; missing keys default to false.

```php
new ParserConfig(usedAttributes: ['lines' => true, 'indexes' => true, 'comments' => true]);
new ParserConfig(['lines' => true]); // PHP syntax without named args
```

--------------------------------

### Invalid PHPDoc type with extra closing brace

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/UPGRADING.md

Another example where the extra '}' was previously consumed as description. In 2.0, this becomes an InvalidTagValueNode.

```php
/** @return array{foo: int}} */
```

--------------------------------

### Lexer class signature with constructor and tokenize method

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/Lexer.md

Full class skeleton showing the private $config and $regexp properties, the constructor storing the ParserConfig, and the tokenize() and generateRegexp() method signatures. The tokenize() return type is list<array{string, int, int}>.

```php
class Lexer
{

	private ParserConfig $config; // @phpstan-ignore property.onlyWritten

	private ?string $regexp = null;

	public function __construct(ParserConfig $config)
	{
		$this->config = $config;
	}

	/**
	 * @return list<array{string, int, int}>
	 */
	public function tokenize(string $s): array
	{
		...
	}

	private function generateRegexp(): string
	{
		...
	}

}
```

--------------------------------

### Accessing VarTagValueNode properties

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/PhpDocTagValues-Parameters.md

Shows how to access the type and variable name from a parsed `@var` tag. The comment shows the expected output for the example docblock.

```php
// '/** @var int $count */'
$var = $phpDocNode->getVarTagValues()[0];
echo $var->type;         // IdentifierTypeNode('int')
echo $var->variableName; // '$count'
```

--------------------------------

### TypelessParamTagValueNode class

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/PhpDocTagValues-Parameters.md

Represents a @param tag with no type declared (starts with &, ..., or $). It has no $type property; distinguish it from ParamTagValueNode using instanceof or tryConsumeTokenType-style checks.

```php
class TypelessParamTagValueNode implements PhpDocTagValueNode
{

	use NodeAttributes;

	public bool $isReference;

	public bool $isVariadic;

	public string $parameterName;

	/** @var string (may be empty) */
	public string $description;

	public function __construct(bool $isVariadic, string $parameterName, string $description, bool $isReference)
	{
		$this->isReference = $isReference;
		$this->isVariadic = $isVariadic;
		$this->parameterName = $parameterName;
		$this->description = $description;
	}

	public function __toString(): string
	{
		$reference = $this->isReference ? '&' : '';
		$variadic = $this->isVariadic ? '...' : '';
		return trim("{$reference}{$variadic}{$this->parameterName} {$this->description}");
	}
}
```

--------------------------------

### Run tests with make tests

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/CLAUDE.md

Runs the PHPUnit test suite using the project's Makefile. Use this to verify all tests pass after code changes.

```bash
make tests
```

--------------------------------

### PhpDocParser class constructor with injected parsers

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/PhpDocParser.md

Class signature and constructor of the top-level 

```php
class PhpDocParser
{

	private const DISALLOWED_DESCRIPTION_START_TOKENS = [
		Lexer::TOKEN_UNION,
		Lexer::TOKEN_INTERSECTION,
	];

	private ParserConfig $config;

	private TypeParser $typeParser;

	private ConstExprParser $constantExprParser;

	private ConstExprParser $doctrineConstantExprParser;

	public function __construct(
		ParserConfig $config,
		TypeParser $typeParser,
		ConstExprParser $constantExprParser
	)
	{
		$this->config = $config;
		$this->typeParser = $typeParser;
		$this->constantExprParser = $constantExprParser;
		$this->doctrineConstantExprParser = $constantExprParser->toDoctrine();
	}
	...
}
```

--------------------------------

### Accessing InvalidTagValueNode exception

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/PhpDocTagValues-MethodTemplate.md

Usage example showing how to detect an InvalidTagValueNode and access its lazily reconstructed ParserException via the magic 'exception' property. The exception is freshly built on each read.

```php
use PHPStan\PhpDocParser\Ast\PhpDoc\InvalidTagValueNode;

$tag = $phpDocNode->getTagsByName('@return')[0];
if ($tag->value instanceof InvalidTagValueNode) {
    $exception = $tag->value->exception; // ParserException, freshly built
    echo $exception->getMessage();
}
```

--------------------------------

### Invalid PHPDoc type without whitespace before description

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/UPGRADING.md

In phpdoc-parser 1.x, this example was silently parsed as an IdentifierTypeNode with the rest as description. In 2.0, it becomes an InvalidTagValueNode because whitespace is required before the description.

```php
/** @return \Closure(...int, string): string */
```

--------------------------------

### Setting and unsetting attributes

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/Ast-Node.md

Shows how to set an attribute with a custom key and unset an attribute by setting it to null.

```php
$tag->setAttribute('myKey', ['anything' => true]);
$tag->setAttribute(Attribute::START_LINE, null); // unsets startLine
```

--------------------------------

### Accessing ArrayShapeNode properties

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/TypeNodes-Advanced.md

Example of accessing an ArrayShapeNode from a parsed PHPDoc return tag. Shows that an unsealed shape has kind 'array', sealed false, an unsealedType of ArrayShapeUnsealedTypeNode, and two items.

```php
use PHPStan\PhpDocParser\Ast\Type\ArrayShapeNode;

// '/** @return array{name: string, age: int, ...<int, string>} */'
$shape = $phpDocNode->getReturnTagValues()[0]->type; // ArrayShapeNode
echo $shape->kind;              // 'array'
echo $shape->sealed;            // false
echo $shape->unsealedType;      // ArrayShapeUnsealedTypeNode(<int, string>)
echo count($shape->items);      // 2
```

--------------------------------

### Handling InvalidTypeNode in type alias

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/TypeNodes-Basic.md

Shows how to detect an `InvalidTypeNode` in a `@phpstan-type` alias and retrieve the original `ParserException` via `getException()`. The example uses a malformed alias with no type after the alias name.

```php
use PHPStan\PhpDocParser\Ast\Type\InvalidTypeNode;
use PHPStan\PhpDocParser\Ast\PhpDoc\TypeAliasTagValueNode;

// '/** @phpstan-type Bad */' — no type after the alias
$aliases = $phpDocNode->getTypeAliasTagValues();
/** @var TypeAliasTagValueNode $alias */
$alias = $aliases[0];
if ($alias->type instanceof InvalidTypeNode) {
    $exception = $alias->type->getException(); // ParserException
    echo $exception->getExpectedTokenType();
}
```

--------------------------------

### Typical parse loop with TokenIterator

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/TokenIterator.md

Typical parse loop as performed inside PhpDocParser. Creates a ParserConfig with usedAttributes: [], tokenizes '/** hello */' with Lexer, then demonstrates currentTokenValue/Type/Offset/Line and consuming tokens until TOKEN_CLOSE_PHPDOC.

```php
use PHPStan\PhpDocParser\ParserConfig;
use PHPStan\PhpDocParser\Lexer\Lexer;
use PHPStan\PhpDocParser\Parser\TokenIterator;

$config = new ParserConfig(usedAttributes: []);
$tokens = new TokenIterator((new Lexer($config))->tokenize('/** hello */'));

echo $tokens->currentTokenValue();   // '/**'
echo $tokens->currentTokenType();    // Lexer::TOKEN_OPEN_PHPDOC
echo $tokens->currentTokenOffset();  // 0
echo $tokens->currentTokenLine();    // 1

$tokens->consumeTokenType(PHPStan\PhpDocParser\Lexer\Lexer::TOKEN_OPEN_PHPDOC);
$tokens->consumeTokenType(PHPStan\PhpDocParser\Lexer\Lexer::TOKEN_PHPDOC_EOL);

while (!$tokens->isCurrentTokenType(PHPStan\PhpDocParser\Lexer\Lexer::TOKEN_CLOSE_PHPDOC)) {
    // process token
    $tokens->next();
}
$tokens->consumeTokenType(PHPStan\PhpDocParser\Lexer\Lexer::TOKEN_CLOSE_PHPDOC);
```

--------------------------------

### VarTagValueNode class definition

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/PhpDocTagValues-Parameters.md

Represents the AST node for `@var`, `@phpstan-var`, `@psalm-var`, and `@phan-var` tags. The variable name is optional; when missing, `$variableName` is `''` and the description starts right after the type.

```php
class VarTagValueNode implements PhpDocTagValueNode
{

	use NodeAttributes;

	public TypeNode $type;

	/** @var string (may be empty) */
	public string $variableName;

	/** @var string (may be empty) */
	public string $description;

	public function __construct(TypeNode $type, string $variableName, string $description)
	{
		$this->type = $type;
		$this->variableName = $variableName;
		$this->description = $description;
	}

	public function __toString(): string
	{
		return trim("$this->type " . trim("{$this->variableName} {$this->description}"));
	}
}
```

--------------------------------

### Run tests directly with phpunit

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/CLAUDE.md

Runs the PHPUnit test suite directly without using the Makefile. Equivalent to `make tests`.

```bash
php vendor/bin/phpunit
```

--------------------------------

### Lexer Class

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/Lexer.md

Documentation for the Lexer class constructor and tokenize method.

```APIDOC
## Constructor

### Description
Creates a new Lexer instance with the given shared parser configuration.

### Method
__construct

### Signature
```php
public function __construct(ParserConfig $config)
```

### Parameters
- **$config** (ParserConfig) - Required - Shared parser configuration. Note: Lexer stores it but never reads its properties; it is kept so all components share one options object.

### Return Type
void
```

```APIDOC
## tokenize

### Description
Tokenizes a PHPDoc source string into a flat list of tokens. Each token is represented as an array with the token value, type, and line number. The last token is always the end-of-input token. Tokenizing never fails; unrecognized characters become TOKEN_OTHER.

### Method
tokenize

### Signature
```php
public function tokenize(string $s): array
```

### Parameters
- **$s** (string) - Required - The PHPDoc source text, e.g. `'/** @param Lorem $a */'`.

### Return Type
`list<array{string, int, int}>` - One entry per token: `['value', type, line]`. The last entry is always the end-of-input token `['', Lexer::TOKEN_END, line]`. Line numbers are 1-based; a newline increments the counter for every `TOKEN_PHPDOC_EOL` token.

### Throws
None - tokenizing never fails; any unrecognized character becomes `TOKEN_OTHER`.

### Notes
- On an empty match (e.g. input without `/**`), the method still returns the end token: `[['', self::TOKEN_END, 1]]`.
- The token triple offsets are defined by the constants `Lexer::VALUE_OFFSET = 0`, `Lexer::TYPE_OFFSET = 1`, `Lexer::LINE_OFFSET = 2`.
```

--------------------------------

### Run tests and PHPStan after every change

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/CLAUDE.md

Runs both tests and PHPStan sequentially. This is mandatory after every code change; do not commit until both pass.

```bash
make tests && make phpstan
```

--------------------------------

### new Lexer(ParserConfig)

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/Lexer.md

Creates a new Lexer instance with the given parser configuration. The Lexer is then used to tokenize PHPDoc strings into token triples.

```APIDOC
## new Lexer(ParserConfig)

### Description
Creates a new Lexer instance. The constructor takes a ParserConfig object, which can be configured with `usedAttributes`.

### Method
Constructor

### Usage Example
```php
use PHPStan\PhpDocParser\ParserConfig;
use PHPStan\PhpDocParser\Lexer\Lexer;

$lexer = new Lexer(new ParserConfig(usedAttributes: []));
```

### Parameters
- **config** (ParserConfig) - Required - The parser configuration. In the example, `usedAttributes` is set to an empty array.

### Returns
A new Lexer instance.
```

--------------------------------

### Usage examples for StringUnescaper::unescapeString

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/StringUnescaper.md

Shows how to use the unescapeString method with various string literals, including single-quoted, double-quoted with escape sequences, and Unicode codepoints. The comments indicate the expected output.

```php
use PHPStan\PhpDocParser\Parser\StringUnescaper;

echo StringUnescaper::unescapeString("'it\\'s'");   // "it's"
echo StringUnescaper::unescapeString('"a\\nb"');     // "a\nb" (actual newline)
echo StringUnescaper::unescapeString('"\\u{1F600}"'); // "😀"

// PHP source form:
echo StringUnescaper::unescapeString("'a\\\n'b");   // single-quoted: only \\ and \' are special
```

--------------------------------

### NodeAttributes trait implementation

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/Ast-Node.md

Provides private attribute storage with methods to set, check, and get attributes. Setting a null value removes the key. getAttribute returns null if the key is absent.

```php
trait NodeAttributes
{

	/** @var array<string, mixed> */
	private array $attributes = [];

	/**
	 * @param mixed $value
	 */
	public function setAttribute(string $key, $value): void
	{
		if ($value === null) {
			unset($this->attributes[$key]);
			return;
		}
		$this->attributes[$key] = $value;
	}

	public function hasAttribute(string $key): bool
	{
		return array_key_exists($key, $this->attributes);
	}

	/**
	 * @return mixed
	 */
	public function getAttribute(string $key)
	{
		if ($this->hasAttribute($key)) {
			return $this->attributes[$key];
		}

		return null;
	}

}
```

--------------------------------

### Constructing and printing by hand

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/PhpDocNode.md

Constructing and printing PhpDocNode manually.

```APIDOC
## Constructing and printing by hand

### Description
Construct a `PhpDocNode` manually and print it.

### Classes
- `PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocNode`
- `PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTagNode`
- `PHPStan\PhpDocParser\Ast\PhpDoc\GenericTagValueNode`
- `PHPStan\PhpDocParser\Printer\Printer`

### Example
```php
use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocNode;
use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTagNode;
use PHPStan\PhpDocParser\Ast\PhpDoc\GenericTagValueNode;
use PHPStan\PhpDocParser\Printer\Printer;

$phpDoc = new PhpDocNode([
    new PhpDocTagNode('@since', new GenericTagValueNode('1.0')),
]);
echo $phpDoc;                    // "/**\n * @since 1.0\n */" (PHP calls __toString)
echo (new Printer())->print($phpDoc);
```

### Edge Case
A lone `'/** */'` parses to a `PhpDocNode` with `children === []`.
```

--------------------------------

### Accessing parsed @param tag value

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/PhpDocTagValues-Parameters.md

Shows how to access a parsed @param tag value from a PhpDocNode. The example demonstrates retrieving the type, variadic flag, and parameter name from the first parameter tag.

```php
// '/** @param int ...$args a description */'
$value = $phpDocNode->getParamTagValues()[0];
echo $value->type;          // IdentifierTypeNode('int')
echo $value->isVariadic;    // true
echo $value->parameterName; // '$args'
```

--------------------------------

### Basic PHPDoc Parsing with PhpDocParser

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/CLAUDE.md

Basic usage of the phpdoc-parser library: instantiate ParserConfig, Lexer, ConstExprParser, TypeParser, and PhpDocParser, then tokenize and parse a PHPDoc string.

```php
$config = new ParserConfig(usedAttributes: []);
$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);
```

--------------------------------

### Parse a type with TypeParser and print variance

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/TypeParser.md

Directly parse a PHPDoc type using the token pipeline. Requires a ParserConfig and ConstExprParser; the example parses a union of a generic with a covariant variance and prints the variance marker.

```php
use PHPStan\PhpDocParser\ParserConfig;
use PHPStan\PhpDocParser\Lexer\Lexer;
use PHPStan\PhpDocParser\Parser\ConstExprParser;
use PHPStan\PhpDocParser\Parser\TokenIterator;
use PHPStan\PhpDocParser\Parser\TypeParser;
use PHPStan\PhpDocParser\Ast\Type\UnionTypeNode;
use PHPStan\PhpDocParser\Ast\Type\GenericTypeNode;

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

$open = new TokenIterator((new Lexer($config))->tokenize('/** @return Collection<covariant T>|null */'));
$open->consumeTokenType(PHPStan\PhpDocParser\Lexer\Lexer::TOKEN_OPEN_PHPDOC);
$open->next(); // consume the tag token '@return'

$type = $typeParser->parse($open); // UnionTypeNode
/** @var array $types */
$types = $type->types;
/** @var GenericTypeNode $generic */
$generic = $types[0];
echo $generic->variances[0]; // GenericTypeNode::VARIANCE_COVARIANT — 'covariant'
```

--------------------------------

### TokenIterator joining and range methods

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/TokenIterator.md

Methods for joining token values and managing ranges. `joinUntil` concatenates token values until the current type matches one of the passed types. `next()` advances and skips irrelevant tokens. `forwardToTheEnd()` sets the index to the last token. `getContentBetween` returns raw source text between token indexes and throws `LogicException` if the range is invalid. `getTokenCount()` returns the total number of tokens.

```php
/** @phpstan-impure */
public function joinUntil(int ...$tokenType): string

public function next(): void

public function forwardToTheEnd(): void

public function getTokens(): array

public function getContentBetween(int $startPos, int $endPos): string

public function getTokenCount(): int
```

--------------------------------

### Inspect InvalidTypeNode and get expected token type

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/errors.md

Use when a type inside @phpstan-type, @psalm-type, or @phan-type fails to parse. The tag is preserved as TypeAliasTagValueNode with an InvalidTypeNode placeholder; getException() rebuilds the original ParserException and __toString() renders '*Invalid type*'.

```php
use PHPStan\PhpDocParser\Ast\Type\InvalidTypeNode;
use PHPStan\PhpDocParser\Ast\PhpDoc\TypeAliasTagValueNode;

$alias = $phpDocNode->getTypeAliasTagValues()[0]; // TypeAliasTagValueNode
if ($alias->type instanceof InvalidTypeNode) {
    $e = $alias->type->getException();
    echo $e->getExpectedTokenType(); // what the type parser expected
}
```

--------------------------------

### Inspecting constant expressions from PHPDoc nodes

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/ConstExprNodes.md

Shows how to access method tag values and their default parameter values, and how to create a ConstExprArrayNode. The example notes that in normal PHPDoc types an array literal is invalid and yields InvalidTypeNode, but in Doctrine mode it is valid.

```php
use PHPStan\PhpDocParser\Ast\ConstExpr\ConstExprArrayNode;
use PHPStan\PhpDocParser\Ast\ConstExpr\ConstExprIntegerNode;
use PHPStan\PhpDocParser\Ast\PhpDoc\MethodTagValueNode;

// '/** @method Foo bar(int $x = 1) */'
$method = $phpDocNode->getMethodTagValues()[0]; // MethodTagValueNode
$default = $method->parameters[0]->defaultValue; // ConstExprIntegerNode('1')
echo $default->value; // '1' — a string

// '/** @return {1, 'k' => 2} */' — Doctrine array in an annotation value;
// in normal PHPDoc types an array literal is invalid and yields InvalidTypeNode
$arr = new ConstExprArrayNode([]);
echo $arr; // '[]'
```

--------------------------------

### ParserConfig::__construct

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/ParserConfig.md

Creates a ParserConfig instance with the given used attributes array. Missing keys default to false.

```APIDOC
## ParserConfig::__construct

### Description

Creates a ParserConfig instance that determines which node attributes the parsers should compute. The constructor accepts an array with optional boolean keys 'lines', 'indexes', and 'comments'.

### Method

Constructor

### Signature

```php
public function __construct(array $usedAttributes)
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$usedAttributes` | `array{lines?: bool, indexes?: bool, comments?: bool}` | yes | — | Which node attributes the parsers should compute. Missing keys default to `false`. The literal keys accepted are exactly `'lines'`, `'indexes'`, `'comments'`; no other keys are read. |

### Behavior Notes

- Setting a key to `false` is the same as omitting it.
- `lines` and `indexes` are required when using `Printer::printFormatPreserving()`; `comments` is also required so inline comments can be re-inserted when printing.
- The constructor never throws.

### Example

```php
$config = new ParserConfig(usedAttributes: ['lines' => true, 'indexes' => true, 'comments' => true]);
```
```

--------------------------------

### Using GenericTypeNode to inspect variances

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/TypeNodes-Advanced.md

Shows how to access the variance and generic type arguments from a parsed return type. The example assumes a doc comment with '@return Collection<covariant T, *>' and demonstrates that the second generic type is an IdentifierTypeNode('mixed') representing the '*' bivariant argument.

```php
use PHPStan\PhpDocParser\Ast\Type\GenericTypeNode;

// '/** @return Collection<covariant T, *> */'
$g = $phpDocNode->getReturnTagValues()[0]->type; // GenericTypeNode
echo $g->variances[0]; // 'covariant'
echo $g->genericTypes[1]; // IdentifierTypeNode('mixed') (from '*')
```

--------------------------------

### Basic tokenization with Lexer

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/Lexer.md

Creates a Lexer with a ParserConfig and tokenizes a PHPDoc comment. The resulting tokens are triples of [text, token type, line number], with the last entry being TOKEN_END.

```php
use PHPStan\PhpDocParser\ParserConfig;
use PHPStan\PhpDocParser\Lexer\Lexer;

$lexer = new Lexer(new ParserConfig(usedAttributes: []));
$tokens = $lexer->tokenize('/** @param Lorem $a */');

// $tokens[0] == ['/**', Lexer::TOKEN_OPEN_PHPDOC, 1]
// $tokens[1] == [' ',       Lexer::TOKEN_HORIZONTAL_WS, 1]
// $tokens[2] == ['@param',  Lexer::TOKEN_PHPDOC_TAG, 1]
// last entry   == ['',       Lexer::TOKEN_END, 1]
```

--------------------------------

### toDoctrine

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/ConstExprParser.md

Returns a new ConstExprParser instance with Doctrine string parsing enabled.

```APIDOC
## toDoctrine

### Description
Returns a new ConstExprParser instance that shares the same configuration but has Doctrine string parsing enabled.

### Method
toDoctrine

### Signature
```php
public function toDoctrine(): self
```

### Parameters
None.

### Returns
- A new ConstExprParser instance with Doctrine string parsing enabled.
```

--------------------------------

### Run PHPStan with make phpstan

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/CLAUDE.md

Runs PHPStan static analysis using the project's Makefile. Use this to check for static analysis errors.

```bash
make phpstan
```

--------------------------------

### Accessing template tag properties

Source: https://github.com/phpstan/phpdoc-parser/blob/2.3.x/_autodocs/api-reference/PhpDocTagValues-MethodTemplate.md

Example of accessing a parsed @template tag value. Given the doc comment '/** @template T of Foo = Bar desc */', this retrieves the first template tag value and prints its name, upper bound, and default type. The bound and default are returned as IdentifierTypeNode instances.

```php
// '/** @template T of Foo = Bar desc */'
$template = $phpDocNode->getTemplateTagValues()[0];
echo $template->name;    // 'T'
echo $template->bound;   // IdentifierTypeNode('Foo')
echo $template->default; // IdentifierTypeNode('Bar')
```
Tokens:
Raw