michaelschiemer/src/Framework/Reflection/README.md

# Reflection Module

The Reflection module provides a powerful, efficient, and developer-friendly API for PHP reflection operations. It enhances PHP's native reflection capabilities with caching, lazy loading, batch operations, and a fluent interface.

## Features

- **Caching**: Dramatically improves performance for repeated reflection operations
- **Lazy Loading**: Only loads reflection data when needed, reducing memory usage
- **Batch Operations**: Efficiently process multiple classes or methods at once
- **Fluent API**: Intuitive builder pattern for reflection operations
- **Interface Segregation**: Focused interfaces for specific reflection needs
- **PHP 8.x Support**: Full support for attributes (PHP 8.0+) and enums (PHP 8.1+)
- **Memory Optimization**: Advanced memory management to prevent leaks and reduce footprint

## Basic Usage

```php
use App\Framework\Core\ValueObjects\ClassName;
use App\Framework\Reflection\CachedReflectionProvider;

// Create a reflection provider
$reflection = new CachedReflectionProvider();

// Get information about a class
$class = $reflection->getClass(ClassName::create(MyClass::class));

// Check if a class has an attribute
$hasAttribute = $reflection->hasAttribute(
    ClassName::create(MyClass::class), 
    MyAttribute::class
);

// Get method parameters
$parameters = $reflection->getMethodParameters(
    ClassName::create(MyClass::class), 
    'myMethod'
);

// Create a new instance
if ($reflection->isInstantiable(ClassName::create(MyClass::class))) {
    $instance = $class->newInstance('arg1', 'arg2');
}
```

## Advanced Usage

### Fluent API with ReflectionBuilder

```php
use App\Framework\Reflection\Builder\ReflectionBuilderFactory;

// Get information about a class
$class = ReflectionBuilderFactory::forClass(MyClass::class)
    ->getClass();

// Get information about a method
$method = ReflectionBuilderFactory::forMethod(MyClass::class, 'myMethod')
    ->getMethod();

// Check if a class has a specific attribute
$hasAttribute = ReflectionBuilderFactory::forClassWithAttribute(
    MyClass::class, 
    MyAttribute::class
)->hasAttribute();

// Create a new instance
$instance = ReflectionBuilderFactory::forClass(MyClass::class)
    ->newInstance('arg1', 'arg2');
```

### Batch Operations

```php
use App\Framework\Reflection\BatchOperations\ReflectionBatchProcessor;
use App\Framework\Reflection\CachedReflectionProvider;

// Create a batch processor
$provider = new CachedReflectionProvider();
$batchProcessor = new ReflectionBatchProcessor($provider);

// Get attributes for multiple classes
$attributes = $batchProcessor->getAttributesForClasses([
    MyClass1::class,
    MyClass2::class,
    MyClass3::class
], RouteAttribute::class);

// Get methods with a specific attribute
$methods = $batchProcessor->getMethodsWithAttribute([
    Controller1::class,
    Controller2::class,
    Controller3::class
], RouteAttribute::class);
```

### Working with Enums

```php
use App\Framework\Core\ValueObjects\ClassName;
use App\Framework\Reflection\CachedReflectionProvider;

$reflection = new CachedReflectionProvider();
$enumClass = ClassName::create(StatusEnum::class);

// Check if a class is an enum
if ($reflection->isEnum($enumClass)) {
    // Get all enum cases
    $cases = $reflection->getEnumCases($enumClass);
    
    // Check if enum has a specific case
    if ($reflection->hasEnumCase($enumClass, 'ACTIVE')) {
        // Get the enum case
        $case = $reflection->getEnumCase($enumClass, 'ACTIVE');
    }
    
    // Check if enum is backed
    if ($reflection->isBackedEnum($enumClass)) {
        // Get backing type
        $type = $reflection->getEnumBackingType($enumClass);
        
        // Get backing value for a case
        $value = $reflection->getEnumCaseBackingValue($enumClass, 'ACTIVE');
    }
}
```

### Specialized Interfaces

The module provides specialized interfaces for specific reflection needs:

```php
use App\Framework\Reflection\Contracts\ClassReflector;
use App\Framework\Reflection\Contracts\MethodReflector;
use App\Framework\Reflection\Contracts\AttributeReflector;
use App\Framework\Reflection\CachedReflectionProvider;

class MyService {
    public function __construct(
        // Only depend on what you need
        private ClassReflector $classReflector,
        private MethodReflector $methodReflector,
        private AttributeReflector $attributeReflector
    ) {}
    
    // Or use the complete implementation for all capabilities
    public function withComplete(CachedReflectionProvider $reflection) {
        // ...
    }
}
```

## Performance Considerations

The Reflection module is optimized for performance, but reflection operations can still be expensive. Consider these best practices:

- **Cache Warming**: Pre-warm the cache for frequently used classes
- **Lazy Loading**: Use lazy loading for classes that might not be needed
- **Batch Operations**: Use batch operations for processing multiple classes
- **Memory Management**: Call `flush()` to clear the cache when done with a large batch
- **Environment Configuration**: Use development mode during development for better debugging

See [EVALUATION.md](EVALUATION.md) for detailed performance analysis and recommendations.

## When to Use

The Reflection module is ideal for:

- Framework-level features that need to analyze many classes
- Applications that need efficient, repeated reflection operations
- Code that benefits from a more developer-friendly reflection API
- Projects that need advanced features like batch operations or lazy loading

For simpler use cases, consider using PHP's native reflection API directly.

## Module Structure

- **Core Components**:
  - `ReflectionProvider`: Main interface combining all reflection capabilities
  - `CachedReflectionProvider`: Complete implementation with caching

- **Specialized Interfaces**:
  - `ClassReflector`: Class-level reflection operations
  - `MethodReflector`: Method-level reflection operations
  - `PropertyReflector`: Property-level reflection operations
  - `ParameterReflector`: Parameter-level reflection operations
  - `AttributeReflector`: Attribute-related reflection operations
  - `EnumReflector`: Enum-related reflection operations (PHP 8.1+)
  - `InstantiationReflector`: Instantiation-related reflection operations
  - `CacheManager`: Cache management operations

- **Performance Optimizations**:
  - `LazyReflectionProxy`: Lazy-loading proxy for ReflectionClass
  - `ReflectionBatchProcessor`: Batch operations for multiple classes
  - `ReflectionBuilder`: Fluent API for reflection operations
  - `ReflectionCache`: Coordinated caching for reflection data

## Further Documentation

- [EVALUATION.md](EVALUATION.md): Detailed analysis of the module's value and overhead
- [Builder/README.md](Builder/README.md): Documentation for the ReflectionBuilder
- [BatchOperations/README.md](BatchOperations/README.md): Documentation for batch operations