Phpdoc Reader Laravel Package

Product Decisions This Supports

• Autowiring / zero-config DI features. This library is the mechanism that lets a container infer a class type from @param Backend $backend when the constructor has no native type hint. Whether we ship "works out of the box on legacy code" is a DX decision, and this package is the cheapest way to enable it.
• Addressable market for untyped codebases. A large share of enterprise PHP code predates scalar type declarations and relies on docblocks. Supporting docblock inference expands who can adopt our container/linter/scaffolder without a code-modernization prerequisite.
• Build vs. buy on parsing. The alternative is hand-rolling namespace, use-import, alias, and relative-namespace resolution ourselves — dozens of edge cases, a known source of bugs. This is a buy (or rather, free-dependency) decision.
• PHP 8 migration roadmap. phpdoc annotations are the legacy path to PHP 8 attributes. Deciding when to add an attributes-first / docblock-fallback strategy is a roadmap item this dependency directly informs.
• Ecosystem alignment. It is the reader behind PHP-DI 6 and Woohoo Labs Zen. If we position as compatible with the PHP-DI ecosystem, this is part of the compatibility surface.
• Tooling use cases beyond DI: code generation scaffolding, static analysis helpers, documentation extraction, and test-double/auto-mocking utilities that need to know "what class does this parameter expect."

When to Consider This Package

Adopt when:

• We are building or refactoring an autowiring layer and need class-name resolution from @var / @param.
• Our target users plausibly run untyped constructor parameters documented via docblocks.
• We need PHP-identical name resolution semantics (FQN, imported, relative, aliased) and do not want to own that logic.
• We want a small, MIT-licensed, single-purpose library rather than pulling in a full AST parser.

Look elsewhere when:

• nikic/php-parser, phpdocumentor/reflection-docblock, or PHPStan is already in our dependency graph — do not add a second parser for one narrow capability.
• We need more than class names: generics, array shapes, union/intersection types, primitive coercion. This library deliberately returns null for @var string.
• Our product is PHP 8+ attributes-first. Attribute reading is out of scope; we would need our own layer regardless.
• We need vendor SLA or long-term support: last release is 2020-10-12, so treat it as stable-but-dormant, not actively maintained. Fork or vendor-pin with an internal patch path.
• We are optimizing a hot path: it is reflection-based and per-call, so we must add caching on our side before adopting it for anything high-frequency.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a tiny, free, MIT-licensed utility that reads @param and @var docblocks and tells us what class a developer intended. It is the piece that lets our product "just work" on older, untyped PHP codebases instead of demanding customers modernize first — a meaningful expansion of who can adopt us, at effectively zero licensing cost and roughly a sprint of engineering saved. It is already proven inside PHP-DI 6, one of the most widely used PHP containers. The one caveat is that its last release was 2020, so we will vendor-pin it and keep a small internal fork path; that is a routine, low-cost mitigation, not a blocker.

For engineering (the practical summary): We get PHP-accurate class-name resolution — fully qualified, use-imported, namespace-relative, and aliased — for free, and we skip writing and testing that logic ourselves. Three integration rules: (1) wrap it behind our own small interface so we can swap in reflection-docblock or attributes later; (2) memoize results per ReflectionProperty / ReflectionParameter, since it is reflection-based and not cheap; (3) pair it with an attributes-first, docblock-fallback strategy so PHP 8+ code is handled natively. Expect it to return class names only — no primitives, no unions, no generics — so anything richer stays our responsibility. Pin the version, run it against our CI matrix, and treat upstream as dormant.