Application Container and Dependency Injection

Purpose and Scope

This document covers the Application container's dependency injection capabilities, service resolution mechanisms, binding systems, and the comprehensive alias registry that enables convenient service access throughout the framework. The Application class (src/Application.php) serves as the central dependency injection container for Hypervel, extending the Hypervel Container which itself builds upon Hyperf's DI system.

For information about service provider registration and the application lifecycle boot process, see Service Providers and Application Lifecycle. For path resolution and environment detection methods, see Application Paths and Environment Detection. For global helper functions that provide static access to container services, see Global Helper Functions.

Application Container Architecture

The Application class is the core container implementation that manages all dependency injection, service binding, and resolution throughout the framework. It extends Hypervel\Container\Container and implements the ApplicationContract interface.

Class Hierarchy and Initialization

Sources: src/Application.php25 src/Contracts/Application.php13

The Application container is initialized during framework bootstrap with the following sequence:

Sources: src/Application.php82-90 src/Application.php92-95

Container Initialization

The constructor performs three critical initialization steps:

1. Base Path Configuration: Sets the application base path, defaulting to the BASE_PATH constant
2. Definition Source Creation: Obtains a DefinitionSourceInterface from DefinitionSourceFactory which configures Hyperf's annotation-based dependency injection
3. Binding Registration: Registers base container bindings and comprehensive alias mappings

Sources: src/Application.php82-95

Core Container Bindings

The Application container registers foundational bindings during initialization to ensure the container can resolve itself and provide basic services.

Base Bindings

The registerBaseBindings() method establishes the container's self-reference:

Binding	Concrete	Purpose
ContainerInterface::class	$this (Application instance)	Enables PSR-11 container resolution

This binding allows the container to inject itself when classes type-hint Psr\Container\ContainerInterface, enabling services to access the container for dynamic resolution.

Sources: src/Application.php108-111

Container Aliases System

The Application container provides an extensive alias system that maps concrete class names to convenient short names and interface contracts. This system enables flexible service resolution where a single service can be accessed through multiple identifiers.

Alias Resolution Flow

Sources: src/Application.php546-664

Core Service Aliases

The registerCoreContainerAliases() method establishes mappings for all major framework services. The alias structure follows a pattern where a primary interface or class name maps to multiple convenient aliases:

Application Container Aliases

Sources: src/Application.php549-557

Console and Configuration Aliases

Primary Interface	Aliases
Hypervel\Foundation\Console\Contracts\Kernel	'artisan'
Hyperf\Contract\ConfigInterface	'config', Hypervel\Config\Contracts\Repository
Psr\EventDispatcher\EventDispatcherInterface	'events', Hypervel\Event\Contracts\Dispatcher
Hyperf\HttpServer\Router\DispatcherFactory	'router'
Psr\Log\LoggerInterface	'log', Hypervel\Log\LogManager

Sources: src/Application.php558-571

Infrastructure Service Aliases

Primary Interface	Aliases
Hypervel\Encryption\Contracts\Encrypter	'encrypter', Hypervel\Encryption\Encrypter
Hypervel\Cache\Contracts\Factory	'cache', Hypervel\Cache\CacheManager
Hypervel\Cache\Contracts\Store	'cache.store', Hypervel\Cache\Repository
Hypervel\Filesystem\Filesystem	'files'
Hypervel\Filesystem\Contracts\Factory	'filesystem', Hypervel\Filesystem\FilesystemManager

Sources: src/Application.php572-588

Translation and Localization Aliases

Primary Interface	Aliases
Hypervel\Translation\Contracts\Loader	'translator.loader', Hyperf\Contract\TranslatorLoaderInterface
Hypervel\Translation\Contracts\Translator	'translator', Hyperf\Contract\TranslatorInterface

Sources: src/Application.php589-596

HTTP Layer Aliases

Primary Interface	Aliases
Psr\Http\Message\ServerRequestInterface	'request', Hyperf\HttpServer\Contract\RequestInterface, Hyperf\HttpServer\Request, Hypervel\Http\Contracts\RequestContract
Hypervel\Http\Contracts\ResponseContract	'response', Hyperf\HttpServer\Contract\ResponseInterface, Hyperf\HttpServer\Response
Hypervel\Router\Router	'router'
Hypervel\Router\Contracts\UrlGenerator	'url', Hypervel\Router\UrlGenerator

Sources: src/Application.php597-628

Database and Persistence Aliases

Primary Interface	Aliases
Hyperf\DbConnection\Db	'db'
Hypervel\Database\Schema\SchemaProxy	'db.schema'
Hyperf\Redis\Redis	'redis'
Hypervel\Session\Contracts\Factory	'session', Hypervel\Session\SessionManager
Hypervel\Session\Contracts\Session	'session.store'

Sources: src/Application.php608-635

Authentication and Security Aliases

Primary Interface	Aliases
Hypervel\Auth\Contracts\Factory	'auth', Hypervel\Auth\AuthManager
Hypervel\Auth\Contracts\Guard	'auth.driver'
Hypervel\Hashing\Contracts\Hasher	'hash'
Hypervel\Cookie\CookieManager	'cookie'
Hypervel\JWT\Contracts\ManagerContract	'jwt', Hypervel\JWT\JWTManager

Sources: src/Application.php610-622

View and Template Aliases

Primary Interface	Aliases
Hyperf\ViewEngine\Contract\FactoryInterface	'view'
Hyperf\ViewEngine\Compiler\CompilerInterface	'blade.compiler'

Sources: src/Application.php629-630

Mail and Notification Aliases

Primary Interface	Aliases
Hypervel\Mail\Contracts\Factory	'mail.manager', Hypervel\Mail\MailManager
Hypervel\Mail\Contracts\Mailer	'mailer'
Hypervel\Notifications\Contracts\Dispatcher	Hypervel\Notifications\Contracts\Factory

Sources: src/Application.php636-643

Queue and Job Processing Aliases

Primary Interface	Aliases
Hypervel\Bus\Contracts\Dispatcher	Hypervel\Bus\Contracts\QueueingDispatcher, Hypervel\Bus\Dispatcher
Hypervel\Queue\Contracts\Factory	'queue', Hypervel\Queue\Contracts\Monitor, Hypervel\Queue\QueueManager
Hypervel\Queue\Contracts\Queue	'queue.connection'
Hypervel\Queue\Worker	'queue.worker'
Hypervel\Queue\Listener	'queue.listener'
Hypervel\Queue\Failed\FailedJobProviderInterface	'queue.failer'

Sources: src/Application.php644-656

Validation Aliases

Primary Interface	Aliases
Hypervel\Validation\Contracts\Factory	'validator'
Hypervel\Validation\DatabasePresenceVerifierInterface	'validation.presence'

Sources: src/Application.php657-659

Service Resolution Mechanisms

The Application container provides multiple mechanisms for resolving services from the container, leveraging both inherited methods from the base Container class and Hyperf's dependency injection system.

Resolution Methods

Direct Resolution via make()

The primary resolution method inherited from the parent Container class:

Array Access Resolution

The Application container implements ArrayAccess, enabling resolution through array syntax:

PSR-11 Container Interface

Standard PSR-11 methods for container resolution:

Sources: src/Application.php25 (extends Container)

Service Resolution Flow

Sources: src/Application.php546-664 for alias resolution

Binding Mechanisms

The Application container inherits comprehensive binding capabilities from the parent Container class, allowing services to be registered and configured before resolution.

Binding Types and Usage

Instance Binding

Register an existing instance directly into the container:

This makes the exact instance available for all subsequent resolutions.

Sources: src/Application.php110 (example usage in registerBaseBindings)

Singleton Binding

Register a service that should only be instantiated once:

Transient Binding

Register a service that creates a new instance on each resolution:

Alias Registration

Create aliases for existing bindings:

Sources: src/Application.php546-664 demonstrates alias registration pattern

Dependency Injection Container Integration

The Application container integrates with Hyperf's annotation-driven dependency injection system through the DefinitionSourceInterface. This enables:

1. Annotation-Based Injection: Classes can use Hyperf's @Inject annotations
2. Constructor Injection: Automatic resolution of constructor parameters
3. Method Injection: Automatic resolution when calling methods via $app->call()
4. Property Injection: Support for property-based injection through annotations

Sources: src/Application.php92-95 (DefinitionSourceFactory usage)

Method Invocation and Dependency Injection

The Application container provides the call() method for invoking callbacks with automatic dependency injection:

This enables controllers, middleware, and other components to receive their dependencies automatically without manual resolution.

Sources: src/Application.php426 (example usage in bootProvider)

Container Extension and Customization

Macroable Trait Integration

The Application class uses the Macroable trait, allowing runtime extension of the container:

Sources: src/Application.php27

Container Binding Context

When binding services, the container instance is available as $app within closure bindings, providing full access to:

• All registered services via array access or make()
• Configuration via $app['config']
• Events dispatcher via $app['events']
• Any other registered service through aliases

This enables complex service initialization with multiple dependencies:

Sources: src/Application.php546-664 pattern demonstrated in alias registrations