Overview

Purpose and Scope

This document provides an overview of the hypervel/container package, a Laravel-style dependency injection container built on top of the Hyperf framework. This page covers the package's architecture, core components, and integration with the Hyperf ecosystem. For installation and basic usage instructions, see Getting Started. For detailed implementation specifics, see Container System.

Package Overview

The hypervel/container package extends Hyperf's dependency injection system with Laravel-style API patterns while maintaining full compatibility with Hyperf's existing DI infrastructure and PSR-11 standards.

Property	Value
Package Name	hypervel/container
Namespace	Hypervel\Container
PHP Requirement	^8.2
Primary Dependencies	hyperf/di ~3.1.0, hyperf/context ~3.1.0
License	MIT
PSR Compliance	PSR-11 Container Interface

Sources: composer.json1-41

System Architecture

The hypervel/container package consists of three architectural layers: a core container layer that extends Hyperf's base functionality, a configuration layer that manages dependency definitions, and a specialized method invocation layer that provides automatic dependency injection for callables.

Architecture Diagram: Component relationships showing inheritance and composition

Sources: src/Container.php1-20 composer.json22-26

Core Components

The package is organized into several key components, each serving a distinct role in the dependency injection system.

Component Overview Table

Component	File	Primary Responsibility	Extends/Implements
Container	src/Container.php:17	Main DI container implementation with Laravel-style API	Hyperf\Di\Container
Container Contract	src/Contracts/Container.php	Defines container interface contract	Hyperf\Contract\ContainerInterface
BoundMethod	src/BoundMethod.php	Resolves and invokes callables with dependency injection	N/A
DefinitionSourceFactory	src/DefinitionSourceFactory.php	Aggregates dependency definitions from configuration files	N/A
DefinitionSource	src/DefinitionSource.php	Stores and manages service definitions	Hyperf\Di\Definition\DefinitionSource
Scanner	src/Scanner.php	Discovers and registers aspects for AOP	Hyperf\Di\Annotation\Scanner
ScanConfig	src/ScanConfig.php	Manages annotation and aspect scan configuration	Hyperf\Di\Annotation\ScanConfig
BindingResolutionException	src/BindingResolutionException.php	PSR-11 compliant exception for resolution failures	PSR-11 exception interfaces

Sources: src/Container.php17 composer.json28-30

Container Extension Model

The Container class extends Hyperf's base container while adding Laravel-compatible features. The following diagram illustrates the specific features added by this extension.

Extension Features Diagram: Features added to Hyperf's base container

Sources: src/Container.php17-95 src/Container.php467-514

Data Structures

The container maintains several internal data structures to support its functionality.

Internal Container State

Data Structure	Type	Purpose	File Reference
methodBindings	Closure[]	Stores custom method resolution callbacks	src/Container.php24
aliases	string[]	Maps alias names to concrete type names	src/Container.php31
abstractAliases	array[]	Reverse mapping of aliases by abstract type	src/Container.php38
extenders	array[]	Service modification callbacks applied during resolution	src/Container.php45
reboundCallbacks	array[]	Callbacks fired when a binding is replaced	src/Container.php52
globalBeforeResolvingCallbacks	Closure[]	Global callbacks fired before any resolution	src/Container.php59
globalResolvingCallbacks	Closure[]	Global callbacks fired during resolution	src/Container.php66
globalAfterResolvingCallbacks	Closure[]	Global callbacks fired after resolution	src/Container.php73
beforeResolvingCallbacks	array[]	Type-specific callbacks fired before resolution	src/Container.php80
resolvingCallbacks	array[]	Type-specific callbacks fired during resolution	src/Container.php87
afterResolvingCallbacks	array[]	Type-specific callbacks fired after resolution	src/Container.php94

Sources: src/Container.php19-94

Resolution Pipeline

The container implements a multi-stage resolution pipeline when resolving services via the make() method.

Resolution Pipeline Diagram: The sequence of operations during service resolution

Sources: src/Container.php109-132

Method Invocation System

The BoundMethod class provides automatic dependency injection for arbitrary callables. The Container::call() method delegates to this system.

Method Invocation Diagram: How the container resolves and invokes callables with dependencies

Sources: src/Container.php437-440 src/Container.php264-295

Configuration System Integration

The container receives its initial service definitions from the DefinitionSourceFactory, which aggregates configurations from multiple sources.

Configuration Loading Diagram: How dependency definitions flow into the container

Sources: src/Container.php17 composer.json22-26

Aspect-Oriented Programming Support

The container includes scanning infrastructure for aspect-oriented programming through the Scanner and ScanConfig classes.

Component	Responsibility	Configuration Files
Scanner	Discovers and registers aspects	config/aspects.php, config/annotations.php
ScanConfig	Manages scan settings and cache	Provider configurations
AspectCollector	Stores registered aspects (Hyperf)	N/A

Sources: composer.json22-26

Error Handling

The container throws BindingResolutionException for resolution failures, implementing PSR-11's ContainerExceptionInterface for standard error handling across container implementations.

Common Exception Scenarios:

• Service cannot be resolved
• Circular dependency detected
• Missing required constructor parameter
• Invalid binding definition

Sources: src/Container.php435

Global Container Instance

The container integrates with Hyperf's ApplicationContext to provide a globally accessible singleton instance.

Global Instance Management Diagram: How the singleton container instance is managed

Sources: src/Container.php683-692 src/Container.php9

ArrayAccess Interface

The container implements PHP's ArrayAccess interface, allowing array-like syntax for binding and resolution operations.

Operation	Array Syntax	Method Equivalent
Check binding	isset($container[$key])	$container->bound($key)
Resolve service	$container[$key]	$container->get($key)
Bind service	$container[$key] = $value	$container->define($key, $value)
Remove binding	unset($container[$key])	$container->remove($key)

Sources: src/Container.php702-720

Key Differences from Hyperf Base Container

This container extends Hyperf's base container with the following enhancements:

1. Alias System: Type aliasing with recursive resolution (src/Container.php31-38 src/Container.php623-628)
2. Method Bindings: Custom resolution for specific class methods (src/Container.php24 src/Container.php264-295)
3. Lifecycle Callbacks: Before/during/after resolving hooks (src/Container.php59-94 src/Container.php467-514)
4. Extenders: Post-resolution instance modification (src/Container.php45 src/Container.php314-324)
5. Rebound Callbacks: Notifications when bindings are replaced (src/Container.php52 src/Container.php388-419)
6. Conditional Binding: bindIf() for non-overwriting binds (src/Container.php302-307)
7. Method Invocation: call() with automatic dependency injection (src/Container.php437-440)

Sources: src/Container.php17 src/Container.php19-95