Reflection Utilities

Purpose and Scope

This document covers the Reflector utility class, which provides methods for inspecting PHP callables and analyzing parameter type information using PHP's reflection API. These utilities are primarily used internally by the framework for dependency injection, method resolution, and type introspection.

For string manipulation and pattern matching, see String Utilities. For control flow utilities like retry() and tap(), see Control Flow Helpers.

Overview

The Reflector class (src/Reflector.php13) is a static utility class that wraps and extends PHP's built-in reflection capabilities. It provides five key methods for analyzing callables and parameter types:

Method	Purpose	Return Type
isCallable()	Enhanced callable checking with PHP 7.4 compatibility	bool
getParameterClassName()	Extract single class name from parameter type hint	?string
getParameterClassNames()	Extract all class names including union types	array
getTypeName()	Resolve type name with 'self' and 'parent' support	?string
isParameterSubclassOf()	Check if parameter type extends/implements a class	bool

Sources: src/Reflector.php13-136

Reflector Class Architecture

Sources: src/Reflector.php13-136

Callable Inspection

The isCallable() Method

The isCallable() method (src/Reflector.php18-55) provides a PHP 7.4 compatible implementation of callable validation that properly handles array-based callables with enhanced checking.

Method Signature

Callable Validation Logic

Implementation Details

The method handles four callable formats:

Callable Format	Example	Validation Logic
String function	'strlen'	Native is_callable()
Closure	fn() => true	Native is_callable()
Array (object, method)	[$obj, 'method']	Class existence + method visibility check
Array (class, method)	['Class', 'method']	Static method + __callStatic support

Key Features:

• Validates array structure (src/Reflector.php24-27)
• Checks method existence and visibility (src/Reflector.php42-44)
• Supports magic methods __call and __callStatic (src/Reflector.php46-52)
• Handles syntax-only checking for early validation (src/Reflector.php29-32)

Sources: src/Reflector.php18-55

Parameter Type Inspection

Single Type Extraction

The getParameterClassName() method (src/Reflector.php62-71) extracts the class name from a parameter's type hint, returning null for built-in types.

Example Usage Context

Sources: src/Reflector.php62-71

Union Type Handling

The getParameterClassNames() method (src/Reflector.php78-97) extracts all non-builtin class names from union types, introduced in PHP 8.0.

Union Type Processing Flow

Type Extraction Examples

Parameter Declaration	Extracted Classes
MyClass $param	['MyClass']
MyClass|YourClass $param	['MyClass', 'YourClass']
string|int $param	[] (all builtin)
MyClass|null $param	['MyClass']
MyClass|string|YourClass $param	['MyClass', 'YourClass']

Sources: src/Reflector.php78-97

Type Name Resolution

Resolving Special Type Names

The getTypeName() method (src/Reflector.php105-120) resolves special type keywords like self and parent to their actual class names based on the declaring class context.

Resolution Logic

Type Resolution Table

Type Hint	Declaring Class	Parent Class	Resolved Name
MyClass	Any	Any	MyClass
self	CurrentClass	Any	CurrentClass
parent	ChildClass	ParentClass	ParentClass
parent	ChildClass	None	parent (unresolved)

Sources: src/Reflector.php105-120

Subclass Checking

The isParameterSubclassOf() Method

The isParameterSubclassOf() method (src/Reflector.php128-135) determines if a parameter's type hint extends or implements a given class or interface.

Validation Process

Use Cases

Scenario	Parameter Type	Check Against	Result
Interface implementation	MyService implements ServiceInterface	ServiceInterface	true
Class inheritance	ChildClass extends BaseClass	BaseClass	true
Unrelated classes	ClassA	ClassB	false
Same class	MyClass	MyClass	false

Sources: src/Reflector.php128-135

Integration with Framework Components

Framework Usage Patterns

The Reflector class is used throughout the framework for type introspection and validation:

Sources: src/Reflector.php1-136 src/Facades/Facade.php1-264

Common Usage Scenarios

Use Case	Method Used	Purpose
Constructor injection	getParameterClassNames()	Resolve dependencies for autowiring
Route model binding	getParameterClassName()	Identify model class for implicit binding
Method validation	isCallable()	Verify callback validity before invocation
Interface checking	isParameterSubclassOf()	Ensure parameter implements required interface
Union type support	getParameterClassNames()	Handle PHP 8.0+ union type hints

Sources: src/Reflector.php1-136

Method Reference

Complete API Surface

Method Details

isCallable()

Location: src/Reflector.php18-55

Parameters:

• $var (mixed): The variable to check as callable
• $syntaxOnly (bool): If true, only check syntax without verifying existence (default: false)

Returns: bool - Whether the variable is a valid callable

Key Behavior:

• Non-array values delegate to native is_callable()
• Array callables require valid structure: [class|object, 'methodName']
• Checks method visibility using ReflectionMethod::isPublic()
• Supports __call and __callStatic magic methods

---

getParameterClassName()

Location: src/Reflector.php62-71

Parameters:

• $parameter (ReflectionParameter): The parameter to inspect

Returns: ?string - The class name or null for built-in types

Key Behavior:

• Returns null for built-in types (int, string, bool, etc.)
• Resolves self and parent to actual class names
• Only works with ReflectionNamedType, not union types

---

getParameterClassNames()

Location: src/Reflector.php78-97

Parameters:

• $parameter (ReflectionParameter): The parameter to inspect

Returns: array - Array of class names (empty if all types are built-in)

Key Behavior:

• Handles PHP 8.0+ union types (ReflectionUnionType)
• Filters out built-in types from unions
• Falls back to single type extraction for non-union types
• Returns empty array if no class types found

---

isParameterSubclassOf()

Location: src/Reflector.php128-135

Parameters:

• $parameter (ReflectionParameter): The parameter to inspect
• $className (string): The parent class or interface name to check against

Returns: bool - Whether the parameter's type is a subclass of $className

Key Behavior:

• Returns false if parameter has no class type
• Checks both class existence and interface existence
• Uses ReflectionClass::isSubclassOf() for validation
• Does not return true for the same class (strict subclass check)

Sources: src/Reflector.php1-136