Container System

Purpose and Scope

The Container System is the core dependency injection (DI) mechanism in Hypervel, providing service registration, resolution, and lifecycle management. It extends Hyperf's DI container with additional features including method binding, service decoration, lifecycle callbacks, and a comprehensive alias system.

This document introduces the container architecture, its relationship to Hyperf's base system, and the key components that enable flexible dependency injection. For detailed implementation specifics, see Container Implementation. For the complete API contract, see Container Contract. For service registration patterns, see Service Binding. For resolution mechanics, see Dependency Resolution.

---

Architectural Overview

The Container System is built on top of Hyperf's DI container and adds Laravel-inspired features for enhanced flexibility and developer experience. The architecture consists of two primary components: the Container implementation class and the ContainerContract interface.

Core Components

Diagram 1: Container System Component Hierarchy

Sources: src/Container.php17 src/Contracts/Container.php13

---

Container Class

The Container class is the main implementation that manages service bindings, instances, and dependency resolution. It extends Hyperf\Di\Container and adds seven internal data structures to support advanced DI patterns.

Internal Data Structures

Property	Type	Purpose
$methodBindings	Closure[]	Custom method resolution callbacks
$aliases	string[]	Service name aliases mapping
$abstractAliases	array[]	Reverse alias lookups by abstract name
$extenders	array[]	Service decoration closures
$reboundCallbacks	array[]	Callbacks for service rebinding events
$globalBeforeResolvingCallbacks	Closure[]	Global pre-resolution hooks
$globalResolvingCallbacks	Closure[]	Global resolution hooks
$globalAfterResolvingCallbacks	Closure[]	Global post-resolution hooks
$beforeResolvingCallbacks	array[]	Type-specific pre-resolution hooks
$resolvingCallbacks	array[]	Type-specific resolution hooks
$afterResolvingCallbacks	array[]	Type-specific post-resolution hooks

Sources: src/Container.php24-94

Extension Points

The Container extends Hyperf's base functionality with:

1. Method Binding System: Allows custom resolution logic for specific method calls
2. Alias Management: Provides alternative names for services with recursive resolution
3. Service Decoration: Enables modification of resolved instances via extenders
4. Lifecycle Callbacks: Three-phase callback system for resolution events
5. ArrayAccess Support: Enables array syntax for service access ($container['ServiceName'])

Diagram 2: Container Resolution Pipeline

Sources: src/Container.php109-132 src/Container.php139-146

---

Container Contract Interface

The ContainerContract interface defines the complete API that container implementations must provide. It extends Hyperf's ContainerInterface (which implements PSR-11) and adds methods for:

• Binding management (bind, bindIf, instance)
• Method binding (bindMethod, callMethodBinding)
• Service decoration (extend)
• Alias management (alias, getAlias)
• Lifecycle hooks (beforeResolving, resolving, afterResolving, rebinding)
• Instance management (forgetInstance, forgetInstances, flush)
• Method invocation (call, factory)

Method Categories

Diagram 3: Container Contract Method Organization

Sources: src/Contracts/Container.php13-189

---

Relationship with Hyperf DI

The Container System builds upon Hyperf's DI foundation while maintaining backward compatibility. The inheritance hierarchy ensures that any code expecting a Hyperf container can use the Hypervel container seamlessly.

Inheritance and Interface Compliance

Diagram 4: Container Inheritance and Interface Structure

Sources: src/Container.php10-17 src/Contracts/Container.php8-13

Key Inherited Functionality

From Hyperf\Di\Container, the Hypervel Container inherits:

• Definition Management: Uses DefinitionSource to store service definitions
• Constructor Injection: Automatic parameter resolution via reflection
• Singleton Support: Shared instance management via resolvedEntries cache
• PSR-11 Compliance: Standard get() and has() methods

The Hypervel Container extends this with:

• Alias System: Recursive alias resolution with bidirectional mapping
• Method Bindings: Custom resolution for method invocation
• Extenders: Decorator pattern for modifying resolved services
• Comprehensive Callbacks: Three-phase lifecycle hooks (before/during/after)
• Array Access: Intuitive service access via $container['service']

---

Global Container Instance

The Container can be registered as a global singleton in Hyperf's ApplicationContext, enabling access from anywhere in the application without explicit dependency injection.

Singleton Management

Diagram 5: Global Container Instance Management

Sources: src/Container.php682-701

The getInstance() method provides lazy initialization: if no container exists in the ApplicationContext, it creates a new one with an empty DefinitionSource. The setInstance() method allows replacing the global container, useful for testing or custom bootstrapping.

---

Array Access Support

The Container implements PHP's ArrayAccess interface, enabling intuitive array-style syntax for service management:

Operation	Array Syntax	Container Method
Check existence	isset($container['Service'])	$container->bound('Service')
Retrieve service	$service = $container['Service']	$service = $container->get('Service')
Register service	$container['Service'] = $definition	$container->define('Service', $definition)
Remove service	unset($container['Service'])	$container->remove('Service')

Additionally, the Container supports magic property access:

• $container->Service calls $container['Service'] (retrieval)
• $container->Service = $value calls $container['Service'] = $value (registration)

Sources: src/Container.php703-737

---

Core Operations

The Container System provides three fundamental operations that form the basis of dependency injection:

1. Service Registration

Services are registered using various methods depending on the binding strategy:

• bind(string $abstract, mixed $concrete): Register a binding (creates new instance per resolution)
• bindIf(string $abstract, mixed $concrete): Register only if not already bound
• instance(string $abstract, mixed $instance): Register a pre-existing instance as singleton
• alias(string $abstract, string $alias): Create an alternative name for a service

See Service Binding for detailed registration patterns.

2. Service Resolution

Services are resolved from the container using:

• make(string $name, array $parameters = []): Build a new instance every time
• get(string $id): Retrieve service (may return cached singleton)
• call(callable $callback, array $parameters = []): Invoke method with auto-injection

See Dependency Resolution for resolution mechanics.

3. Service Modification

Already-registered services can be modified:

• extend(string $abstract, Closure $closure): Wrap existing service with decorator
• rebinding(string $abstract, Closure $callback): React to service re-registration
• refresh(string $abstract, mixed $target, string $method): Update dependent objects

See Extenders, Aliases & Method Bindings for modification patterns.

Sources: src/Container.php109-514

---

Integration with Definition Sources

The Container relies on Hyperf's DefinitionSource to store service definitions, but adds capabilities for dynamic definition management:

Diagram 6: Container and DefinitionSource Relationship

The Container's remove() method extends the base functionality by not only clearing the resolved instance but also removing the definition from the source and clearing the definition cache.

Sources: src/Container.php177-189 src/Container.php194-201 src/Container.php614-617

---

Key Differences from Hyperf Container

While maintaining full compatibility with Hyperf's container, Hypervel adds these features:

Feature	Hyperf Container	Hypervel Container
PSR-11 Compliance	✓	✓
Constructor Injection	✓	✓
Singleton Support	✓	✓
Alias System	✗	✓ (with recursive resolution)
Method Bindings	✗	✓
Service Extenders	✗	✓
Lifecycle Callbacks	Limited	✓ (three-phase system)
Rebinding Events	✗	✓
ArrayAccess	✗	✓
Magic Properties	✗	✓
Definition Removal	✗	✓ (via remove())

Sources: src/Container.php17

---

Next Steps

For specific implementation details:

• Container Implementation: See Container Implementation for internal data structures and resolution pipeline details
• Interface Definition: See Container Contract for the complete API contract
• Service Registration: See Service Binding for binding patterns and precedence rules
• Resolution Mechanics: See Dependency Resolution for how services are resolved and dependencies injected
• Advanced Features: See Advanced Container Features for method injection, callbacks, and decoration patterns