phpDocumentor Reflection DocBlock

ReflectionDocBlock is the component that gives phpDocumentor (and dozens of other PHP tools) the ability to actually understand the meaning inside a /** ... */ comment rather than treating it as a plain string. It implements a DocBlockFactory that parses a raw doc comment into a DocBlock object exposing a summary, a description, and a typed collection of tags (@param, @return, @throws, and any custom tag you register).

Because DocBlocks are notoriously inconsistent in real-world code, the library leans on phpstan/phpdoc-parser for type expression parsing and on phpdocumentor/type-resolver and phpdocumentor/reflection-common for resolving those types against a class’s namespace and use-statements. The result is a small, dependency-light building block that annotation readers, static analyzers, and documentation generators use instead of writing their own regex-based DocBlock parsers.

What You Get

• A DocBlockFactory::createInstance() entry point that parses any doc comment string (or an object exposing getDocComment(), like ReflectionClass) into a DocBlock value object
• Structured access to the summary and description, including a Description object that can be rendered back to string with inline tag substitution
• A tag system covering the standard PHPDoc tags (@param, @return, @var, @throws, @see, @method, @property, etc.) plus a StandardTagFactory you can extend with custom tag classes
• Type resolution delegated to phpdocumentor/type-resolver, so @param and @return type strings become real Type objects resolved against the current namespace/use-imports
• A small, focused dependency graph (webmozart/assert, phpstan/phpdoc-parser, doctrine/deprecations) rather than a monolithic reflection framework

Common Use Cases

• Documentation generators (phpDocumentor itself) that need to render a class’s DocBlocks into human-readable API docs
• Static analysis and IDE tooling that needs to read @param/@return type annotations for types PHP’s native reflection can’t express (union types pre-8.0, generics, collection shapes)
• Annotation-driven libraries that store metadata in DocBlock tags (ORMs, validators, routing) and need a reliable parser instead of hand-rolled regex
• Test and mocking frameworks that inspect @covers, @dataProvider, or similar custom tags on methods

Under The Hood

Architecture — The library is a small parsing pipeline: DocBlockFactory::create() strips comment delimiters and asterisks, splits the remaining text into a summary/description block and a tag block, then hands the summary+description to DescriptionFactory and each @tag line to StandardTagFactory/TagFactory, which dispatches to per-tag classes (Param, Return_, Throws, etc. under DocBlock/Tags) based on the tag name. The output is an immutable DocBlock object exposing getSummary(), getDescription(), and getTags(), with tag classes implementing a shared Tag interface so callers can instanceof-check for specific tag types. Tech Stack — Pure PHP (^7.4 || ^8.0) with no runtime framework dependency: phpdocumentor/type-resolver and phpdocumentor/reflection-common for type/FQSEN resolution, phpstan/phpdoc-parser for parsing complex type expressions, webmozart/assert for defensive argument checks, and doctrine/deprecations for soft-deprecation notices. Dev tooling includes PHPUnit, PHPStan (with Mockery and webmozart-assert extensions), Psalm, and a Makefile-driven CI pipeline. Code Quality — 64 test files under tests/unit and tests/integration exercise the factory and individual tag classes; the codebase runs under declare(strict_types=1) throughout, uses final classes and typed properties, and is linted by both PHPStan (with a checked-in baseline) and Psalm, indicating an actively enforced static-analysis bar despite low day-to-day commit velocity. API Design — The public surface is intentionally narrow: one static factory method (DocBlockFactory::createInstance()) to bootstrap, one create() call to parse, and a small set of getters on the resulting DocBlock. This makes integration a two-line affair for consumers, at the cost of needing to reach into DocBlock\Tags\* classes directly when you need tag-specific data (e.g., a Param tag’s variable name and type).