Open-Source Testing · phpstan

phpdoc-parser

phpdoc-parser is a PHP library that reads and modifies PHPDoc comments as structured data (AST). It handles modern PHP type syntax including generics, intersection types, and conditional types, and is the primary parser used by PHPStan static analyzer.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/phpstan/phpdoc-parser

1.5k

GitHub stars

Forks

PHP

Primary language

MIT

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	phpstan/phpdoc-parser
Owner	phpstan
Primary language	PHP
License	MIT — OSI-approved
Stars	1.5k
Forks	74
Open issues	18
Latest release	2.3.3 (2026-07-08)
Last updated	2026-07-08
Source	https://github.com/phpstan/phpdoc-parser

What phpdoc-parser is

A lexer-based PHPDoc tokenizer and recursive-descent parser that builds an Abstract Syntax Tree. Supports type parsing (union, intersection, generic, callable, conditional types), constant expression evaluation, visitor-pattern AST traversal, and format-preserving printing for AST modifications that preserve source layout.

Quickstart

Get the phpdoc-parser source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/phpstan/phpdoc-parser.git2cd phpdoc-parser3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

PHPStan / Static Analysis Integration

Primary use case: feeding PHPDoc type annotations into static analyzers and IDE type checkers. The library is developed alongside PHPStan and handles all modern PHP type syntax.

Code Generation & Refactoring Tools

Build tools that read PHPDoc tags to generate boilerplate, validate annotations, or refactor type hints while preserving formatting. Format-preserving printer enables round-trip modifications.

Documentation & Metadata Extraction

Extract structured metadata from PHPDoc (parameter types, return types, custom tags) for API documentation generators, schema builders, or runtime type reflection systems.

Implementation considerations

Requires explicit Composer install; integrates via dependency injection (instantiate Lexer → TokenIterator → TypeParser → PhpDocParser).
Format-preserving features demand enabling node attributes (lines, indexes, comments) in ParserConfig, adding memory overhead; weigh against modification use case.
Supports Doctrine Annotations via separate AST namespace; ensure your dependency graph is clear if mixing PHPDoc and Doctrine metadata.
Parser is deterministic; no async or streaming. Large batches of PHPDocs should be queued to avoid blocking.
Error recovery: check documentation for partial parse behavior on malformed PHPDoc; exact error handling strategy not detailed in excerpt.

When to avoid it — and what to weigh

Runtime Type Enforcement — This is a parser only; it does not enforce types at runtime. If you need runtime type validation, combine with a runtime assertion library or use PHP 8.0+ attributes.
Non-PHP Codebases — Language-specific to PHP PHPDoc syntax. Not applicable for parsing TypeScript, Java, or other language doc formats.
Legacy PHP < 7.1 Support — The library is modern PHP-focused. If you must support PHP 5.x or early PHP 7, this may not be suitable without adaptation.
Need for Custom PHPDoc Dialect — The parser is tightly aligned with PHPStan's interpretation of PHPDoc spec. Heavy customization of syntax or tag semantics requires forking or wrapping.

License & commercial use

MIT License. Permissive, OSI-approved. Allows use, modification, and distribution in proprietary and open-source projects, provided copyright and license notice are retained.

MIT is a permissive OSI license that explicitly permits commercial use. No commercial support, warranty, or indemnification is provided by the library. Organizations should review license text and consult legal counsel if integrating into mission-critical systems.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Strong
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Good
Assessment confidence	High

Security considerations

Parser processes untrusted PHPDoc strings. Consider: input size limits (DoS via deeply nested types or huge arrays), integer overflow in number parsing, and stack depth for recursive descent. No security audit status provided. Recommend rate-limiting and sandboxing if parsing user-submitted PHP files.

Alternatives to consider

nikic/PHP-Parser

Full PHP AST parser (not just PHPDoc). If you need to parse complete PHP code and extract doc blocks separately, nikic may be more general, but heavier overhead.

Doctrine Annotations

Doctrine provides an annotation parser and runtime validator. Use if your codebase already uses Doctrine ORM and you prefer attribute-based metadata; phpdoc-parser is lighter and PHPStan-aligned.

Custom regex / ad-hoc parsing

For simple, non-recursive PHPDoc extraction (e.g., single @param tags), lightweight regex may suffice. Not recommended for full type syntax support or modification.

Software development agency

Build on phpdoc-parser with DEV.co software developers

phpdoc-parser is battle-tested in PHPStan and ready for static analysis, code generation, and documentation extraction. Let Devco help you integrate it into your development pipeline.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

phpstan phpstan-doctrine phpat

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Testing API Development Custom Software Development Application Development Talk to DEV.co

phpdoc-parser FAQ

Can I use phpdoc-parser to enforce types at runtime?

No. This library parses PHPDoc syntax into AST only. For runtime enforcement, layer a type checker (e.g., Respect\Validation, symfony/validator) or use PHP 8.0+ native attributes and reflection.

Does it support PHP 8 Attributes?

Not directly. The library focuses on PHPDoc comment syntax. PHP 8 native attributes are separate; use PHP's ReflectionAttribute API or parse attributes independently.

What is the format-preserving printer for?

It allows you to modify the AST (e.g., change a type annotation) and print the PHPDoc back in a form as close as possible to the original source (preserving whitespace, line breaks, comment placement), rather than re-serializing from scratch.

Is phpdoc-parser a replacement for PHPStan?

No. phpdoc-parser is a component library that PHPStan uses. PHPStan is the full static analyzer; phpdoc-parser is just the parser. You can use phpdoc-parser independently for other tools.

Software development & web development with DEV.co

DEV.co helps companies turn open-source tools like phpdoc-parser into production software. Our software development services cover the full lifecycle — architecture, web development, integration, and maintenance — delivered by software developers and web developers who ship. Engage our software development agency to implement or customize it for your open-source testing stack.

Integrate Robust PHPDoc Parsing Into Your PHP Tooling

phpdoc-parser is battle-tested in PHPStan and ready for static analysis, code generation, and documentation extraction. Let Devco help you integrate it into your development pipeline.

Talk to DEV.co Schedule a Consultation