Reflection Common Laravel Package

Getting Started

phpdocumentor/reflection-common is a foundational dependency providing shared value objects and interfaces for PHP’s code analysis ecosystem — most notably used by phpdocumentor/reflection (the PHPDoc parser). You’ll rarely install it directly; instead, it’s pulled in as a transitive dependency (e.g., via composer require phpdocumentor/reflection).
First practical step: Use Fqsen::fromString() to parse and validate fully qualified structural names (e.g., \MyApp\Controllers\UserController::index). Start by exploring the src/Fqsen.php, src/Name.php, and src/QualifiedName.php classes — they form the core of type/name normalization in reflection-based tools.

Implementation Patterns

• In Laravel-based tooling or package development:
  • When building API documentation generators or annotation processors (e.g., for custom @route or @apiResource tags), use Fqsen to represent controller/method references robustly instead of raw strings — avoids errors from misnormalized names or missing backslashes.
  • When implementing custom validation for PHPDoc (e.g., in a code quality pipeline), normalize type strings with Name::fromString($type) to resolve relative names (self, static) or aliased imports against context — critical when generating OpenAPI schemas or DTO builders.
  • If authoring a static analysis plugin (e.g., for Pest or PHPUnit coverage), implement the Element or Structure interfaces to integrate with existing reflection consumers — keeps your tool interoperable with tools like phpdocumentor/reflection, nikic/php-parser, or symfony/polyfill.
• With Laravel’s existing ecosystem:
  • Works seamlessly with symfony/property-info (used by Symfony’s Serializer and Form components) where type extraction relies on similar concepts — especially useful when building custom API resource transformers or Laravel Nova field processors.

Gotchas and Tips

• Staleness warning: Last release was in 2020. While stable, do not expect PHP 8.4+ support. For modern projects, consider phpdocumentor/reflection or alternatives like nikic/php-parser directly — this package is best treated as a dependency of higher-level tools, not a first-party dependency.
• Strict typing & PHP constraints: Requires PHP ≥7.1, but phpdocumentor/reflection (which depends on this) requires ≥7.4 and PHP 8+ features (e.g., union types,Attributes). Mixing with legacy Laravel apps (e.g., Laravel 7 on PHP 7.3) may cause runtime issues.
• FQSEN vs Name confusion:
  • Name = unqualified identifier (e.g., User, parent)
  • QualifiedName = namespace-prefixed (e.g., App\Models\User)
  • Fqsen = fully qualified structural element (e.g., \App\Models\User::find() or \App\Models\User::class)
    Using Name where Fqsen is needed (or vice versa) causes silent validation errors — always check the type signature in the library docs you’re consuming.
• Type coercion traps: Many methods accept both strings and objects (e.g., Fqsen|string). Prefer strict usage (Fqsen::fromString($string)) over implicit conversion — Laravel’s string helpers like Str::contains() won’t understand Fqsen objects.
• Debugging tip: Dump objects with dump($fqsen->getFullyQualifiedString()) or (string)$fqsen — never rely on __toString() implicitly. Use var_dump(get_class($object)) when tracing unknown types from docblock parsing.