michaelschiemer/src/Framework/Reflection

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

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

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

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

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:

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 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: Detailed analysis of the module's value and overhead
• Builder/README.md: Documentation for the ReflectionBuilder
• BatchOperations/README.md: Documentation for batch operations