Reflection Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require codememory/reflection
   

   Requires PHP 8.3+ and Symfony Cache component (^7.1).

2. Basic Initialization:

   use Codememory\Reflection\ReflectorManager;
   use Symfony\Component\Cache\Adapter\FilesystemAdapter;
   
   $cache = new FilesystemAdapter('codememory', 'cache');
   $reflectorManager = new ReflectorManager($cache, false); // Disable dev mode for production
   

3. First Use Case: Fetch a class reflector and inspect properties/methods:

   $classReflector = $reflectorManager->getReflector(MyClass::class);
   $properties = $classReflector->getProperties(); // Cached result
   

Implementation Patterns

Core Workflows

1. Reflector Caching:

   • Replace new ReflectionClass() with $reflectorManager->getReflector(ClassName::class).
   • Cache keys are derived from fully qualified class names (e.g., First).

2. Attribute Introspection:

   foreach ($classReflector->getProperties() as $property) {
       foreach ($property->getAttributes() as $attribute) {
           $instance = $attribute->getInstance(); // Cached attribute instance
       }
   }
   

3. Environment-Aware Caching:

   • Pass true as the second argument to ReflectorManager in development to disable caching (forces live reflection).

4. Integration with Laravel:

   • Bind the manager to the container in AppServiceProvider:

     $this->app->singleton(ReflectorManager::class, fn() =>
         new ReflectorManager(app(Cache::class)->getAdapter('codememory'), app()->isLocal())
     );
     

   • Use dependency injection:

     public function __construct(private ReflectorManager $reflectorManager) {}
     

5. Bulk Reflection:

   $reflectors = $reflectorManager->getReflectors([ClassA::class, ClassB::class]);
   

Gotchas and Tips

Pitfalls

1. Cache Invalidation:

   • Clear cache manually after schema changes (e.g., new classes/attributes):

     $cache->clear();
     

   • Use isDev mode during development to bypass cache.

2. Attribute Resolution:

   • Attributes are cached as instances, so changes to attribute logic require cache clearing.

3. Performance Tradeoffs:

   • Caching improves performance but may hide runtime errors (e.g., missing classes) until cache expires.

4. Symfony Cache Dependency:

   • Ensure the cache adapter is properly configured (e.g., filesystem permissions for FilesystemAdapter).

Debugging Tips

1. Cache Inspection:

   $cache->getItem('First')->get(); // Dump cached data
   

2. Dev Mode:

   • Enable isDev mode to debug live reflection:

     $reflectorManager = new ReflectorManager($cache, true);
     

3. Fallback to Native Reflection:

   • For edge cases, extend ReflectorManager to delegate to ReflectionClass when needed.

Extension Points

1. Custom Cache Adapter:

   • Implement Psr\Cache\CacheItemPoolInterface for database/Redis caching.

2. Reflector Decorators:

   • Wrap ReflectorManager to add pre/post-processing:

     class DecoratedReflectorManager {
         public function __construct(private ReflectorManager $manager) {}
     
         public function getReflector(string $class) {
             $reflector = $this->manager->getReflector($class);
             // Add custom logic (e.g., logging)
             return $reflector;
         }
     }
     

3. Attribute Handlers:

   • Override attribute resolution by extending Codememory\Reflection\Reflectors\ClassReflector.