phpDocumentor/ReflectionDocBlock

This system is a PHP library dedicated to parsing, analyzing, and rendering PHPDoc comments. It leverages the PHPStan parser to accurately extract and handle standard and custom tags, such as @param, @return, and @template, while providing robust utilities for description formatting and error handling. The library supports extensible tag factories and configurable output formatters, enabling developers to integrate precise static analysis data into their tooling workflows.

7 changes.

This period focused on modernizing the project by removing legacy DocBlock reflection classes and their associated tests, while upgrading dependencies to support PHP 7.4+ and modern static analysis tools. The test suite was reorganized to include comprehensive code coverage and quality checks, aligning the codebase with current standards.

9 changes.

The DocBlock component underwent a comprehensive refactoring to enforce strict typing, improve PCRE error handling, and modernize tag classes with native PHP features. This architectural overhaul introduced new formatting options and robust factory patterns, accompanied by extensive unit and integration tests to ensure stability and coverage.

4 changes.

The project replaced its legacy DocBlock parsing logic with PHPStan's parser to improve accuracy and robustness. This migration introduced a new factory architecture for handling various tag types and established a refined exception hierarchy for better error management. Comprehensive unit tests were added to verify the new parsing behavior and custom tag implementations.

Two new formatters have been added to the DocBlock tag formatting system: AlignFormatter, which pads tag names so that all tag values align vertically for improved readability, and PassthroughFormatter, which outputs tags with minimal formatting by trimming whitespace. These classes implement the existing Formatter interface and are located in the src/DocBlock/Tags/Formatter namespace, allowing users to choose between structured alignment or simple plain-text output when rendering docblock tags.

src/DocBlock/Tags/Formatter · high confidence

The \DocBlock\ class has been removed from the \phpDocumentor\\Reflection\ namespace. This deletion eliminates the previous implementation that parsed docblock comments into short descriptions, long descriptions, and tags, which may break any code relying on this specific class for docblock reflection.

src/phpDocumentor/Reflection · high confidence

The following DocBlock tag handler classes have been removed from the library: CoversTag, LinkTag, MethodTag, ParamTag, PropertyReadTag, PropertyTag, PropertyWriteTag, ReturnTag, SeeTag, ThrowTag, ThrowsTag, UsesTag, and VarTag. This change eliminates the previous implementation of these tags, which will break any code relying on these specific classes for parsing or handling DocBlock content.

src/phpDocumentor/Reflection/DocBlock/Tag · high confidence

The \LongDescription\ and \Tag\ classes in \src/phpDocumentor/Reflection/DocBlock\ have been removed. This eliminates the previous implementation that handled long description parsing (including inline tag extraction and Markdown formatting) and generic tag instantiation. Users relying on these specific classes for DocBlock reflection will need to adopt the updated API provided by the remaining components in this namespace.

src/phpDocumentor/Reflection/DocBlock · high confidence

The library has replaced its legacy docblock parsing logic with PHPStan's parser (phpstan/phpdoc-parser). This change introduces a new factory architecture in src/DocBlock/Tags/Factory, featuring an AbstractPHPStanFactory and specific factories for tags like @param, @return, @var, @method, @property, @template, and others. For users, this means more robust and accurate parsing of complex PHPDoc types and descriptions, better handling of edge cases like multiline descriptions and typeless parameters, and improved compatibility with modern PHPStan standards.

src/DocBlock/Tags/Factory · high confidence

The library introduces a new set of exception classes in the \src/Exception\ directory to improve error handling. A new \ReflectionDocblockException\ interface serves as the base for specific exceptions, including \ParserException\ (which wraps PHPStan parser errors) and \PcreException\ (which maps PCRE error codes to descriptive messages). Additionally, a \CannotCreateTag\ exception has been added to handle tag creation failures.

src/Exception · high confidence

The DocBlock component has been significantly restructured to improve stability and extensibility. The Description class now uses a body template with sprintf-style placeholders to render text, allowing for cleaner separation of content and tags. A new DescriptionFactory handles parsing, including robust escape sequence support (e.g., \{@}\ for literal \@\) and normalization of superfluous whitespace in multi-line descriptions. The StandardTagFactory has been updated to use a service-locator pattern for dependency injection, enabling easier registration of custom tag handlers and integration with PHPStan-style factories for complex tags like \@param\ and \@return\. Additionally, the Serializer now supports configurable line endings and custom tag formatters, and the ExampleFinder has been refined to reliably locate example files across various project structures.

src/DocBlock · high confidence

The core DocBlock parsing logic has been refactored to enforce strict typing and improve reliability. The DocBlock class now uses native PHP type declarations for its properties and methods, and the factory interface ensures consistent instantiation. A new safe wrapper for preg\_split (Utils::pregSplit) has been introduced to throw explicit exceptions on PCRE errors instead of returning false, preventing silent failures during tag parsing. Additionally, the DocBlock class now supports template markers (\#@+ and \#@-) to propagate descriptions and tags to subsequent docblocks, and provides new methods like getTagsWithTypeByName for more precise tag retrieval.

src · high confidence

The DocBlock tag classes in src/DocBlock/Tags have been rewritten to use modern PHP features, including strict types, type hints, and return types. This refactoring improves code quality and maintainability while ensuring backward compatibility. The changes include updates to existing tags like @param, @return, and @method, as well as the addition of new tags such as @template and @mixin.

src/DocBlock/Tags · high confidence

The library's test suite has been reorganized into distinct 'unit' and 'integration' suites, with the PHPUnit configuration updated to support code coverage reporting and Mockery integration. Additionally, the project now includes a full suite of static analysis and code quality tools, including PHPStan (set to max level), Psalm, PHP\_CodeSniffer, PHPMD, and YAML linting, along with a Makefile to streamline running these checks.

(repo-wide) · high confidence

Added integration tests for DocBlock parsing and tag handling; Added test assets for custom DocBlock tag implementations; Added unit tests for AlignFormatter and PassthroughFormatter; Added unit tests for DocBlock components and coverage checking; Added unit tests for DocBlock parsing and PCRE utilities; Added unit tests for DocBlock tag classes; Added unit tests for DocBlock tag factories; Removed legacy DocBlock unit test; Removed unit tests for DocBlock tag classes.

This release updates the minimum PHP version to 7.4 or 8.0 and upgrades the core dependency \phpdocumentor/type-resolver\ to version 2.0, which in turn requires \phpstan/phpdoc-parser\ 2.0. The package also adds \doctrine/deprecations\ and \webmozart/assert\ as explicit dependencies, switches to PSR-4 autoloading, and updates development tools to support modern static analysis and testing standards.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 50 → 63 (+13.2)
• Rubric changed (rubric-2026.08.15 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 100 → 99 (-0.8)
• Architecture 94 → 90 (-4.1)
• Maturity 57 → 55 (-2.5)
• Readiness 33 → 59 (+26.6)
• Security 57 → 74 (+17.1)

• Coverage not measured — test suite did not build
• Dimension evaluation failed
• Duplicated block (8 lines × 2) (src/DocBlock/StandardTagFactory.php)
• High: security finding (details withheld)
• No exposed public API
• No tests found
• Test reliability not included
• The README is thin on usage examples and omits any mention of how to extract metadata from DocBlocks beyond the factory-createInstance example. (README.md)

• Ambiguous naming convention for filtering tags. 'getTagsByName' implies filtering by tag name (e.g., '@param'), while 'getTagsWithTypeByName' is confusingly named—it likely filters by type within tags of a specific name, or filters by type name. The 'With' preposition is unclear. It is not immediately obvious if 'getTagsByName' returns all tags of that name regardless of type, or if it's a subset.
• Change coupling clique: Param.php, Property.php, PropertyRead.php, PropertyWrite.php, Var_.php (src/DocBlock/Tags/Param.php)
• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• Duplicated block (10 lines × 4) (src/DocBlock/Tags/Property.php)
• Duplicated block (16 lines × 3) (src/DocBlock/Tags/Property.php)
• Duplicated block (6 lines × 4) (src/DocBlock/Tags/Property.php)
• Duplicated block (9 lines × 2) (src/DocBlock/Tags/Covers.php)
• Duplicated block (9 lines × 2) (src/DocBlock/Tags/Deprecated.php)
• Duplicated block (9 lines × 3) (src/DocBlock/Tags/Covers.php)
• Duplicated block (9 lines × 3) (src/DocBlock/Tags/Covers.php)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Inverted test pyramid
• …and 22 more

• 2 commits — 2 feature/other, 0 fixes

• (repo) — 1 commit
• (root) — 1 commit

• change: Merge pull request #462 from donatj/patch-1
• change: Remove Scrutinizer Code Quality badge

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

phpDocumentor/ReflectionDocBlock was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.