 |
VOOZH | about |
|
VOOZH | about |
This document covers three advanced container features that provide dynamic service manipulation and indirection capabilities:
These features complement the core binding and resolution mechanisms documented in Service Binding and Dependency Resolution. For lifecycle callback hooks that execute during resolution, see Lifecycle Callbacks. For general method invocation with dependency injection, see Method Invocation & Dependency Injection.
Extenders provide a decorator pattern implementation at the container level, allowing services to be modified or wrapped after resolution but before being returned to the caller. Each extender is a closure stored in the $extenders property that receives the resolved instance and returns a potentially modified instance.
Sources: src/Container.php40-45 src/Container.php314-324 src/Container.php632-643
Diagram: Extender Application During Service Resolution
Sources: src/Container.php109-132 src/Container.php632-635
The container maintains extenders in the $extenders property:
This is a two-dimensional array where the first key is the abstract type name, and the value is an array of closures to be applied in sequence.
Sources: src/Container.php40-45
Extenders are registered using the extend() method:
| Method Signature | Parameters | Purpose |
|---|---|---|
extend(string $abstract, Closure $closure): void | $abstract: Service identifier$closure: Decorator function | Register an extender for a service type |
The extender closure receives two parameters:
$service - The resolved service instance$container - The container instanceAnd must return the (potentially modified) service instance.
Sources: src/Container.php314-324
Diagram: Extender Application During Service Resolution
Sources: src/Container.php109-132 src/Container.php632-635
When extend() is called on a service that has already been resolved, the extender is applied immediately to the cached instance in $resolvedEntries:
Diagram: Immediate Extender Application
Sources: src/Container.php314-324
| Use Case | Example |
|---|---|
| Decoration | Wrapping a logger service with additional context |
| Configuration | Applying runtime configuration to a service |
| Event Wrapping | Adding event dispatch around service method calls |
| Monitoring | Injecting performance monitoring or tracing |
| Testing | Swapping out parts of a service in test environments |
| Method | Purpose |
|---|---|
forgetExtenders(string $abstract): void | Remove all extenders for a given type |
Sources: src/Container.php640-643
The alias system provides an indirection layer through the $aliases and $abstractAliases properties that allows multiple identifiers to resolve to the same underlying service. This enables flexibility in service naming and backwards compatibility when service identifiers change.
Sources: src/Container.php27-38 src/Container.php374-383
The container maintains two complementary data structures for alias management:
| Property | Structure | Purpose |
|---|---|---|
$aliases | ['alias' => 'abstract'] | Forward lookup: alias to concrete |
$abstractAliases | ['abstract' => ['alias1', 'alias2']] | Reverse lookup: concrete to aliases |
Sources: src/Container.php27-38
Aliases are registered using the alias() method:
Diagram: Alias Registration Process
The method prevents self-aliasing to avoid infinite recursion:
Sources: src/Container.php374-383
The getAlias() method recursively resolves aliases to their final abstract type:
Diagram: Recursive Alias Resolution in getAlias() Method
This recursive approach supports alias chains: 'A' -> 'B' -> 'C' where 'A' and 'B' both ultimately resolve to 'C'.
Sources: src/Container.php622-627
Alias resolution is integrated into all major container operations:
| Method | Alias Integration Point |
|---|---|
make() | Resolves alias at entry src/Container.php111-113 |
get() | Resolves alias at entry src/Container.php141-143 |
set() | Resolves alias before storing src/Container.php155-157 |
unbind() | Resolves alias before unbinding src/Container.php167-169 |
remove() | Resolves alias before removal src/Container.php179-181 |
bound() | Resolves alias before checking src/Container.php196-198 |
has() | Checks if identifier is alias src/Container.php213 |
resolved() | Resolves alias before checking src/Container.php221-223 |
Sources: src/Container.php109-227
| Method | Return Type | Purpose |
|---|---|---|
isAlias(string $name): bool | bool | Check if identifier is an alias |
getAlias(string $abstract): string | string | Resolve alias to final abstract |
Sources: src/Container.php231-234 src/Container.php622-627
When registering an instance, aliases are cleaned up to prevent conflicts:
Diagram: Alias Cleanup in instance() Method
Sources: src/Container.php329-367
| Use Case | Example |
|---|---|
| Interface Binding | alias(LoggerInterface::class, 'logger') |
| Legacy Support | Maintain old service names during refactoring |
| Convenience Names | Short names for commonly used services |
| Multiple Facades | Different entry points to the same service |
Method bindings stored in the $methodBindings property allow registration of custom resolution callbacks for specific method invocations. When Container::call() is used to invoke a method, if a binding exists for that method, the binding closure is executed instead of the default parameter resolution logic.
Sources: src/Container.php20-24 src/Container.php262-296
Method bindings are stored as a flat array with keys in class@method format.
Sources: src/Container.php20-24
Method bindings use the class@method string format:
Diagram: Method Identifier Format Conversion in parseBindMethod()
The parseBindMethod() helper converts both array and string formats to the canonical string format:
Sources: src/Container.php280-287
| Method | Parameters | Purpose |
|---|---|---|
bindMethod(array|string $method, Closure $callback): void | $method: Method identifier$callback: Resolution closure | Bind custom resolution for a method |
The callback closure receives two parameters:
$instance - The object instance the method belongs to$container - The container instanceSources: src/Container.php272-275
Method bindings integrate with the BoundMethod::call() system:
Diagram: Method Binding Resolution Sequence
Sources: src/Container.php437-440 src/Container.php264-267 src/Container.php292-295
| Method | Return Type | Purpose |
|---|---|---|
hasMethodBinding(string $method): bool | bool | Check if method has a binding |
callMethodBinding(string $method, mixed $instance): mixed | mixed | Execute the bound closure |
Sources: src/Container.php264-267 src/Container.php292-295
| Use Case | Example |
|---|---|
| Custom Validation | Override parameter resolution for specific methods |
| Performance Optimization | Bypass full DI for known simple cases |
| Testing | Inject mock parameters for specific method calls |
| Legacy Support | Adapt old method signatures to new container |
| Special Context | Provide context-specific parameters |
The refresh() method is a convenience utility that combines rebinding() with property injection, allowing automatic updates when a service is rebound.
| Method | Parameters | Return Type | Purpose |
|---|---|---|---|
refresh(string $abstract, mixed $target, string $method) | $abstract: Service to watch$target: Object to update$method: Setter method name | mixed | Register automatic property refresh on rebind |
Sources: src/Container.php402-407 src/Contracts/Container.php103
The refresh() method wraps rebinding() to automatically call a setter method on a target object:
Diagram: refresh() Method Implementation
Sources: src/Container.php402-407
The refresh() method is particularly useful when an object holds a reference to a container service that may be rebound:
| Scenario | Without refresh() | With refresh() |
|---|---|---|
| Service rebound | Manual update required | Automatic update via setter |
| Multiple dependents | Update each manually | Single refresh() call per dependent |
| Testing | Must remember to sync | Container handles synchronization |
Diagram: Integration of Extenders, Aliases, and Method Bindings
Sources: src/Container.php109-132 src/Container.php437-440
Combine aliases with extenders for flexible service decoration:
Diagram: Alias and Extender Interaction
This pattern allows the same extender to apply whether the service is resolved via alias or concrete name because extend() stores extenders by the final abstract name after alias resolution.
Method bindings can themselves use the container to resolve dependencies:
Diagram: Method Binding with Container Dependency Resolution
Multiple aliases can form resolution chains:
| Alias | $aliases[$alias] | Final Resolution via getAlias() |
|---|---|---|
'log' | 'logger' | LoggerInterface::class |
'logger' | LoggerInterface::class | LoggerInterface::class |
The getAlias() method recursively resolves through the entire chain.
Sources: src/Container.php622-627
| Operation | Extenders | Aliases | Method Bindings |
|---|---|---|---|
dropStaleInstances() | Not affected | Removed for abstract | Not affected |
flush() | Not cleared | Cleared completely | Not cleared |
forgetExtenders() | Removed for abstract | Not affected | Not affected |
removeAbstractAlias() | Not affected | Removed bidirectionally | Not affected |
Sources: src/Container.php648-651 src/Container.php672-677 src/Container.php640-643 src/Container.php354-367
Diagram: Service Lifecycle with Extensions, Aliases, and Bindings
Sources: src/Container.php109-132 src/Container.php314-324 src/Container.php374-383
This document covered three advanced container features:
Container::call()These features integrate seamlessly with the core resolution pipeline and lifecycle callbacks, enabling sophisticated dependency injection patterns without modifying service implementations.
Sources: src/Container.php1-738
Refresh this wiki