PHPDoc Parser

phpstan/phpdoc-parser is the phpDoc parsing library that powers PHPStan. It tokenizes phpDoc comments with a dedicated lexer and parses them into a rich abstract syntax tree, understanding advanced type syntax including generics, conditional types, intersection and union types, and other extended annotations that traditional docblock parsers miss.

Beyond parsing, the library provides a printer that can serialize the AST back to text, making it suitable for tooling that reads, analyzes, and rewrites phpDoc. It is battle-tested at massive scale as the annotation backbone of PHPStan’s static analysis engine.

What You Get

• A Lexer that tokenizes raw phpDoc comment strings
• A PhpDocParser and TypeParser that build a typed AST from the token stream
• A comprehensive AST node model covering tags, types, generics, conditional and intersection types
• A Printer that serializes the AST back to phpDoc text for rewriting workflows
• A ParserConfig for opting into modern parsing behavior and language features

Common Use Cases

• Extracting and analyzing type information from phpDoc for static analysis
• Building IDE tooling that understands generics and advanced annotation syntax
• Rewriting or normalizing docblocks programmatically via the printer
• Powering code generators that read type hints from phpDoc comments

Under The Hood

Architecture - The library is cleanly layered under src/: Lexer/ converts phpDoc text into tokens, Parser/ consumes those tokens to build nodes, Ast/ defines the node hierarchy (PhpDoc tags, type nodes, expression nodes), and Printer/ walks the AST to emit text. A central ParserConfig object toggles parsing behavior, letting consumers opt into newer syntax handling without breaking existing callers.

Tech Stack - Pure PHP (PHP 7.4+), distributed via Composer with no runtime dependencies. It is developed alongside PHPStan and validated in CI with PHPStan’s own static analysis, PHPUnit, and coding-standard checks.

Code Quality - As the parsing core of a widely used static analyzer, the library carries an extensive PHPUnit test suite, is itself analyzed at PHPStan’s strictest level, and follows a strict coding standard. Its 100+ releases reflect careful, incremental evolution with backward-compatibility discipline via ParserConfig.

API Design - The API separates lexing, parsing, and printing into distinct, composable classes, so consumers wire exactly the stages they need. AST nodes are strongly typed value objects, making traversal predictable, and the printer round-trips the tree back to text, which is a strong ergonomic win for rewriting tools.