Annotations Laravel Package

Getting Started

• Context: This package parses docblock annotations (e.g., @Route("/path")) — not PHP 8+ attributes. Given the deprecation warning in the README, avoid using it in new projects unless maintaining legacy code.
• First use case: Extract annotations from a class/method docblock in frameworks like Symfony or Doctrine ORM/DBAL (which still rely on annotations in older versions).
• Where to start:
  • Install: composer require doctrine/annotations
  • Use AnnotationReader to parse docblocks:

    use Doctrine\Common\Annotations\AnnotationReader;
    $reader = new AnnotationReader();
    $reader->getClassAnnotations(new ReflectionClass(MyClass::class));
    

  • Check the official docs for usage patterns.

Implementation Patterns

• Annotation classes: Define annotation classes (e.g., @Entity) with public properties or constructor parameters. They must live in a PSR-4 autoloading namespace (e.g., App\Annotations).
• Caching for performance: Use CachedReader or PsrCachedReader (preferred in v2+) with a PSR-6/PSR-16 cache to avoid re-parsing docblocks on each request:

  $reader = new CachedReader(
      new AnnotationReader(),
      new SymfonyComponentCacheAdapterArrayAdapter()
  );
  

• Integration with Symfony: Configure via annotations config in config/packages/framework.yaml (enable enabled: true or null for auto-detect).
• Custom readers: Override default behavior by extending AnnotationReader (e.g., to support namespaced aliases or custom fallbacks).

Gotchas and Tips

• ⚠️ Deprecation warning: PHP 8 attributes replaced annotations as the native standard. Use them instead unless supporting PHP <8.0 or legacy code (e.g., Symfony <5.4).
• Avoid eval() pitfalls: The parser uses eval() internally for parsing — avoid dynamic docblocks with user input to prevent RCE risks.
• Cache warmup matters: For production, always warm annotation caches (e.g., via php bin/console cache:pool:clear annotations in Symfony) — stale caches cause silent failures.
• Reserved annotations: Annotations like @phpstan, @psalm, @readonly, @noinspection are ignored by default. Add new reserved names via AnnotationReader::addGlobalIgnoredName().
• Variadic params: v2.0.1+ allows annotation constructors with variadic parameters — older versions fail silently on this pattern.
• Debug tip: Use ReflectionMethod::getDocComment() to verify docblock formatting before parsing. Malformed docblocks (e.g., missing @) cause ReflectionException.