Reflection Docblock Laravel Package

Getting Started

Install via Composer: composer require mpociot/reflection-docblock. Start by wrapping a standard ReflectionClass, ReflectionMethod, or ReflectionProperty with the package’s DocBlock factory. The most common first use case is extracting annotations like @Route, @ParamConverter, or custom meta tags for dependency injection or routing frameworks.

use Mpociot\Reflection\DocBlock;

$reflection = new ReflectionClass(MyController::class);
$docBlock = DocBlock::create($reflection);

// Get the full description
$description = $docBlock->getDescription();

// Get specific tags
$routes = $docBlock->getTagsByName('Route');
$params = $docBlock->getTagsByName('Param');

// Get all tags as objects
foreach ($docBlock->getTags() as $tag) {
    echo $tag->getName() . ': ' . $tag->getContent();
}

Begin with the DocBlock::create() factory—works for any Reflection* object. Check for tags and descriptions; ignore @internal unless explicitly needed.

Implementation Patterns

• Static metadata extraction: Use in CLI tools or compile-time analyzers to generate configuration from annotated classes (e.g., CLI commands, services).
• Framework routing integrations: Map HTTP routes to controller methods by reading @Route("/path", methods={"GET"}) annotations on method docblocks.
• Validation/DTO factories: Parse @Assert\Type("string") or custom validation annotations to drive runtime validation or serialization logic.
• Code generators: Feed docblock metadata into template engines (Twig, etc.) for boilerplate generation.
• DI container extensions: Auto-wire properties or constructors using @Inject, @Autowired from docblocks.

Integration tip: Keep DocBlock instantiation lightweight—always pass in the reflected object, never raw strings (for correct @param/@var type inference and context). Cache results per class/method in your tooling to avoid repeated parsing.

Gotchas and Tips

• Last updated in 2016: While stable, it lacks support for PHP 8+ native attributes (#[Attribute]). Only parses /** */ DocBlocks—use phpdocumentor/reflection-docblock (its maintained successor) for modern PHP projects unless locked to older codebases.
• Tag parsing is naive: @Route("/path") returns raw content; rely on getTagsByName() and manually parse content or extend with custom Tag handlers. Use getContent() then regex only as fallback.
• Missing type hints: @var and @param types are returned as raw strings—handle union types and nullable indicators (e.g., ?string) yourself unless you normalize strings.
• Edge case handling: It does normalize line endings and strip leading */@ characters reliably, but nested quotes or multiline @Annotation blocks may need manual cleanup.
• Extensibility: No official hook points—but you can subclass DocBlock and override extractTags() if deeper parsing (e.g., custom AST handling) is required.
• Debugging: If getTagsByName() returns empty, inspect $docBlock->getTags()—sometimes misformatted annotations (e.g., @Route(… missing closing parenthesis) cause silent failures. Enable strict linting on your PHPDocs first.