# Reflection Builder

The Reflection Builder provides a fluent API for reflection operations, making it easier to chain operations and improve code readability.

## Basic Usage

```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();

// Get class attributes
$attributes = ReflectionBuilderFactory::forClass(MyClass::class)
    ->getClassAttributes();

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

// Get method parameters
$parameters = ReflectionBuilderFactory::forMethod(MyClass::class, 'myMethod')
    ->getMethodParameters();

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

## Advanced Usage

### Filtering Methods

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

// Get only public methods
$publicMethods = ReflectionBuilderFactory::forClassWithFilteredMethods(
    MyClass::class, 
    \ReflectionMethod::IS_PUBLIC
)->getMethods();

// Get only methods with a specific attribute
$methods = ReflectionBuilderFactory::forClassWithAttribute(
    MyClass::class, 
    MyAttribute::class
)->getMethods();
```

### Working with Attributes

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

// Get all attributes of a class
$attributes = ReflectionBuilderFactory::forClass(MyClass::class)
    ->getClassAttributes();

// Get all attributes of a method
$methodAttributes = ReflectionBuilderFactory::forMethod(MyClass::class, 'myMethod')
    ->getMethodAttributes();

// Get attributes of a specific type
$routeAttributes = ReflectionBuilderFactory::forClassWithAttribute(
    MyClass::class, 
    RouteAttribute::class
)->getClassAttributes();

// Check if a method has a specific attribute
$hasAttribute = ReflectionBuilderFactory::forMethodWithAttribute(
    MyClass::class, 
    'myMethod', 
    RouteAttribute::class
)->hasAttribute();
```

### Custom Reflection Provider

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

// Create a custom reflection provider
$provider = new CachedReflectionProvider(
    null, // Use default cache
    null, // Use default factory
    'development' // Use development environment
);

// Use the custom provider
$class = ReflectionBuilderFactory::forClass(MyClass::class, $provider)
    ->getClass();
```

### Manual Builder Creation

```php
use App\Framework\Reflection\Builder\ReflectionBuilder;
use App\Framework\Reflection\Builder\ReflectionBuilderFactory;
use App\Framework\Core\ValueObjects\ClassName;

// Create a builder manually
$builder = ReflectionBuilderFactory::create();

// Configure the builder
$builder->forClass(MyClass::class)
    ->method('myMethod')
    ->withAttribute(RouteAttribute::class);

// Use the builder
$method = $builder->getMethod();
$attributes = $builder->getMethodAttributes();
```

## Benefits

- **Fluent Interface**: Chain method calls for better readability
- **Type Safety**: Strong typing with PHP 8.x features
- **Simplified API**: Common operations are simplified
- **Reusable**: Configure once, use multiple times
- **Extensible**: Easy to extend with new operations

## Implementation Details

The Reflection Builder is implemented using two main classes:

- `ReflectionBuilder`: The main builder class that provides the fluent API
- `ReflectionBuilderFactory`: A factory for creating pre-configured builders

The builder delegates to the underlying `ReflectionProvider` for the actual reflection operations, providing a more user-friendly API on top of it.
