Enable Discovery debug logging for production troubleshooting
- Add DISCOVERY_LOG_LEVEL=debug - Add DISCOVERY_SHOW_PROGRESS=true - Temporary changes for debugging InitializerProcessor fixes on production
This commit is contained in:
201
src/Framework/Reflection/README.md
Normal file
201
src/Framework/Reflection/README.md
Normal file
@@ -0,0 +1,201 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user