Reflection Docblock Laravel Package

Getting Started

This package provides a robust DocBlock parser compatible with the PHPDoc standard. It's primarily used behind the scenes by tools like laravel-ide-helper, but can be leveraged directly for custom annotation processing or reflection-based tooling. Start by installing it via Composer:

composer require barryvdh/reflection-docblock

Then parse a DocBlock like this:

use phpDocumentor\Reflection\DocBlock;

$doc = <<<DOCBLOCK
/**
 * @param int $id
 * @return string
 */
DOCBLOCK;

$reflection = new DocBlock($doc);
echo $reflection->getTags()[0]->getName(); // 'param'

First use case: extract type hints and annotations from controller or service methods to generate documentation, configuration, or validation rules.

Implementation Patterns

• Use with Reflection classes: Pass ReflectionMethod, ReflectionClass, or ReflectionProperty objects directly to the parser:

  $method = new ReflectionMethod(MyClass::class, 'myMethod');
  $docBlock = new DocBlock($method);
  

• Integrate in code generators: Use in CLI tools or build steps to inspect classes (e.g., Doctrine-like metadata extraction) and generate stubs, routes, or DTOs.
• Custom annotation parsers: Iterate over tags ($docBlock->getTags()) and match tag names (e.g., @route, @rule) to implement custom behavior—ideal for framework-agnostic annotation systems.
• Leverage ContextFactory (v2.3.0+): Use ContextFactory::create() for more accurate type resolution, especially with namespaced types or generics.

Gotchas and Tips

• Deprecated advice: The README explicitly warns this is a fork tailored for IDE Helper; unless you need its specific tweaks or bug fixes for older PHP versions, prefer phpdocumentor/reflection-docblock (v4+).
• PHP 8.0+ compatibility: While v2.2.0+ includes fixes for PHP 8.4 deprecations, ensure you’re on the latest patch version—earlier versions may misparse union types or true/false literals.
• Trailing whitespace quirks: v2.4.0+ auto-trims empty lines and whitespace, which may break expectations in strict whitespace-sensitive DocBlock content (e.g., ASCII diagrams or alignment-sensitive markup).
• Generics support: v2.2.0+ handles nested generics (e.g., Collection<int, User>), but context matters—use ContextFactory::create() with namespace info for reliable resolution.
• Debug tip: Dump the parsed structure with var_dump($docBlock->getTags()) or json_encode($docBlock->getDecoratedObject()) (if available) to inspect hidden properties or malformed tags.