Weave Code
Reflection Docblock Laravel Package
phpdocumentor/reflection-docblock
PHPDoc-compliant DocBlock parser from phpDocumentor. Parse summaries, descriptions and tags from doc comments or reflection objects using DocBlockFactory, enabling annotation-like metadata and easy access to structured DocBlock information.
At a glance
Frequently asked questions about Reflection Docblock
- How do I install phpdocumentor/reflection-docblock in a Laravel project?
- Run `composer require phpdocumentor/reflection-docblock` in your project root. The package is lightweight (~1MB) and has no Laravel-specific dependencies, so it integrates seamlessly with Composer’s autoloader. No additional configuration is needed for basic usage.
- Can this package parse DocBlocks from ReflectionClass objects in Laravel?
- Yes. Use `DocBlockFactory::createInstance()` to create a factory, then pass a `ReflectionClass` object (e.g., from Laravel’s native reflection) to the `create()` method. It will automatically read the doc comment via `getDocComment()`. Example: `$factory->create((new ReflectionClass(MyClass::class))->getDocComment())`.
- Does this work with Laravel’s custom annotations like @Route or @Cacheable?
- Absolutely. This package fully supports PHPDoc-compliant tags, including custom ones. For example, you can extract `@Route` or `@Cacheable` annotations programmatically to build dynamic middleware or caching logic. Test edge cases like mixed whitespace or malformed tags in your Laravel-specific docblocks.
- What Laravel versions and PHP versions does this package support?
- The package supports PHP 8.4+, aligning with Laravel 10.x/11.x LTS. It has no Laravel-specific dependencies, so it works across all modern Laravel versions. For legacy projects, pin to version 5.x to avoid breaking changes in 6.x (planned for 2025).
- How can I integrate this into Laravel’s service container?
- Register the `DocBlockFactory` as a singleton in a service provider: `$this->app->singleton(DocBlockFactory::class, fn() => DocBlockFactory::createInstance());`. Then inject it into classes or commands via constructor injection. For global access, create a facade (e.g., `DocBlock::parse()`) to wrap the factory logic.
- Is this package suitable for parsing DocBlocks in Laravel tests (e.g., @dataProvider)?
- Yes. Use it in Pest/PHPUnit extensions to dynamically extract test metadata from DocBlocks. For example, parse `@dataProvider` tags to auto-generate test cases or validate test annotations at runtime. Combine with Laravel’s testing tools for seamless integration.
- What are the alternatives to phpdocumentor/reflection-docblock for Laravel?
- Alternatives include `phpstan/phpdoc-parser` (lighter, but less feature-rich) and `rubix/ml` (for PHPDoc parsing). However, this package is the most mature and PHPDoc-compliant option, with active maintenance and Laravel-friendly integration patterns. Avoid `phpdocumentor/phpdocumentor` (full suite) unless you need its additional tools.
- How do I handle non-standard or legacy DocBlock formats in Laravel?
- This package prioritizes PHPDoc compliance but may struggle with legacy formats. Test with your Laravel-specific docblocks (e.g., `@mixin`, `@template`) and use the `DocBlockFactory`’s error handling to log or skip malformed blocks. For critical projects, pre-process docblocks or implement a custom parser wrapper.
- Can I use this for runtime annotation processing (e.g., dynamic middleware)?
- Yes. Parse DocBlocks at runtime to extract annotations like `@Middleware` or `@Cacheable` and apply them dynamically. For example, use it in Laravel’s `BootstrapServiceProvider` to register classes based on docblock tags. Pair with Laravel’s service container for dependency injection.
- What’s the performance impact of parsing DocBlocks in a large Laravel codebase?
- The package is optimized for speed, with minimal overhead (~1MB footprint). Benchmark parsing in your Laravel app (e.g., during `php artisan optimize`). For large codebases, cache parsed DocBlocks in memory or use Laravel’s cache system to avoid repeated parsing.
Weaver
How can I help you explore Laravel packages today?