Phpdoc Parser Laravel Package

Product Decisions This Supports

• Build vs. buy on PHP code intelligence. Any roadmap item that requires understanding PHP types at the docblock level — custom static-analysis rules, type-aware linters, dependency-graph or API-contract extraction — starts here rather than with regexes or a hand-rolled grammar. Buying an AST (MIT, no vendor lock-in) removes weeks of parser maintenance from the critical path.
• PHPStan / Psalm ecosystem investment. Extensions and custom rules for PHPStan are the primary consumer of this library. If the team ships internal static-analysis rules or a quality gate product, this is the substrate that makes those rules expressible.
• Automated refactoring and codemods. The format-preserving printer enables safe, surgical rewrites of @param/@return/@var/generic annotations — e.g., migrating array<string, Foo> styles, normalizing union order, or converting Doctrine annotations to PHP attributes — without reformatting unrelated comments. This is a distinct capability from "parse and read," and it directly unlocks a migration-tooling feature.
• Documentation and contract generation. Array shapes, object shapes, callable signatures, conditional types, and generic variance are all modeled as nodes, so machine-readable API contracts and generated reference docs can be derived from source-of-truth docblocks.
• Adoption/migration tooling for legacy PHP. Doctrine annotation parsing means existing annotation-driven codebases can be analyzed and mechanically modernized, a common enterprise upgrade driver (PHP 8 attributes, PHP 8.5 readiness signaled in CI).
• Not a decision driver: the package does not parse PHP code itself, does not execute annotations at runtime, and does not provide the type-checking engine — it is a component, not a platform. Treat it as infrastructure that a feature is built on, not a feature.

When to Consider This Package

Adopt when:

• The product is PHP and needs to programmatically reason about docblock types, not just display them — generic types, intersection types, array/object shapes, conditional types, callable signatures, constant expressions.
• You are building or extending static analysis (PHPStan/Psalm rules), an IDE/language-server capability, a doc linter, or an API-surface extractor.
• You need to modify docblocks in place while preserving formatting — codemods, annotation→attribute migration, bulk type normalization.
• You need source position mapping (line numbers, token indexes, comments as node attributes) to report findings back to developers.
• You want to inherit PHPStan's evolving PHPDoc dialect for free instead of tracking a spec yourself.

Look elsewhere when:

• Requirements are shallow — extracting @deprecated or a single @author tag is cheaper with a targeted regex, and a full AST is over-engineering.
• You need to parse PHP code (classes, methods, control flow) rather than comments; that is nikic/php-parser territory, and the two are complementary, not substitutes.
• You need runtime annotation reading/validation (Doctrine's runtime layer) rather than compile-time analysis.
• The stack is not PHP, or the team has standardized on a different analyzer whose internal AST is the intended extension point.
• You require vendor-backed SLAs or a multi-maintainer support contract — this is a focused, effectively single-steward open-source project; budget for the (real but modest) risk of pinning a version and carrying patches.

Diligence notes: MIT license is clean for commercial embedding. Release cadence is active and 2.3.x is current with PHP 8.5 in CI. The "0 dependents" figure understates reality — the library is a transitive dependency of PHPStan, so real-world exposure is far larger than the metric implies; validate against your own composer why output rather than the registry count.

How to Pitch It (Stakeholders)

For executives (one paragraph): We can accelerate a class of roadmap items — code quality gates, automated PHP upgrades, generated API documentation — by standing on an established, MIT-licensed PHPDoc parser instead of building one. It is the parsing engine behind PHPStan, is actively released, and supports modern PHP type syntax that regex-based approaches cannot handle. The decision is low-cost and reversible: no license fees, no data leaving our codebase, and the integration surface is a Composer dependency. The main watch-item is that it is a small, focused open-source project, so we should pin versions and expect to carry trivial patches rather than rely on a vendor SLA. Recommendation: adopt as an internal infrastructure dependency where a feature genuinely needs type-level understanding of docblocks; do not adopt it for shallow tag-reading.

For engineering (the short version): phpstan/phpdoc-parser gives us a typed AST for docblocks with a visitor-based traversal (AbstractNodeVisitor + NodeTraverser, with DONT_TRAVERSE_CHILDREN / STOP_TRAVERSAL / REMOVE_NODE controls), a CloningVisitor for safe deep copies, and a format-preserving Printer that round-trips edits with minimal diff noise. Setup is four objects (ParserConfig, Lexer, TypeParser/ConstExprParser, PhpDocParser); enable lines/indexes/comments attributes only when you need position mapping or the printer, since they cost tokens. Coverage includes generics with variance, intersection types, array and object shapes, conditional types, offset access, constant expressions, and Doctrine annotations. Node classes implement __set_state(), so ASTs can be cached or exported. It parses comments only — pair it with nikic/php-parser when we also need to walk PHP code, and keep a regression fixture suite around our own docblock dialect so upstream dialect changes surface in CI rather than in production.