Phpdoc Parser Laravel Package

Getting Started

Start by installing the package via Composer: composer require phpstan/phpdoc-parser. Then, instantiate the parser pipeline: configure ParserConfig with required attributes (e.g., ['lines' => true, 'indexes' => true] for format-preserving operations), initialize Lexer, ConstExprParser, TypeParser, and PhpDocParser. Parse raw PHPDoc strings using TokenIterator wrapped around tokenized input, then access structured AST nodes (e.g., getParamTagValues(), getType()) for inspection or transformation. The simplest first use case: extract parameter names and types from a docblock to validate or generate documentation.

Implementation Patterns

• AST-driven analysis: Use PhpDocNode to inspect annotations (e.g., @param, @return, @template) and traverse typed nodes like IdentifierTypeNode, GenericTypeNode, or IntersectionTypeNode for static analysis.
• Format-preserving modification: Apply AST edits (e.g., renaming a type in @param) using NodeTraverser with CloningVisitor, then output modified PHPDocs via Printer::printFormatPreserving()—ideal for code transformers, fixers (like Rector), or linting tools.
• Doctrine annotation support: Parse Doctrine-style annotations (e.g., @ORM\Entity) using the PHPStan\PhpDocParser\Ast\PhpDoc\Doctrine namespace—configure parser with appropriate flags and leverage attribute nodes like DoctrineAnnotationTagValueNode.
• Custom parsing logic: Extend ConstExprParser or TypeParser for domain-specific PHPDoc extensions (e.g., custom generics or templated types), integrating with downstream tools like IDE plugins or schema validators.

Gotchas and Tips

• Token attributes are critical: Missing lines/indexes in ParserConfig breaks format-preserving printing—always enable them when editing and re-outputting docblocks.
• Newline sensitivity: The parser handles newlines conservatively; unexpected formatting diffs often stem from textBetweenTagsBelongsToDescription setting or missing EOL token skipping (especially with Doctrine annotations on a single line).
• Null-safe access: Always validate getParamTagValues() returns at least one item before accessing index 0; empty or malformed PHPDocs yield empty arrays.
• Node immutability: AST nodes are immutable—use NodeTraverser + CloningVisitor to safely modify trees instead of direct property assignment.
• Debugging tip: Use var_dump($phpDocNode) on parsed nodes to inspect structure, or enable Xdebug tracing to trace parser behavior across TypeParser/ConstExprParser boundaries.
• Extensibility: Add support for experimental features (e.g., custom type aliases) by implementing custom TypeParser subclasses and wiring them into your pipeline.