Container Contract

The Container Contract defines the public interface for the Hypervel dependency injection container. This interface extends Hyperf's ContainerInterface, adding Hypervel-specific features while maintaining compatibility with the Hyperf framework and PSR-11 standards.

For implementation details of this interface, see Container Implementation. For usage patterns of service binding and resolution, see Service Binding and Dependency Resolution.

Sources: src/Contracts/Container.php1-189

Interface Definition

The Container interface serves as the contract between application code and the container implementation. It extends Hyperf\Contract\ContainerInterface, inheriting standard methods like make() and get(), then adds approximately 30 additional methods specific to Hypervel's enhanced container functionality.

Sources: src/Contracts/Container.php13

Method Categories

The interface defines methods across six functional categories:

Category	Method Count	Purpose
Introspection	5	Query container state (bound, resolved, aliases)
Binding Registration	6	Register services and their configurations
Resolution	6	Retrieve and instantiate services
Lifecycle Callbacks	5	Hook into resolution pipeline
Container Management	5	Remove bindings, clear caches
Accessors & Utilities	3	Retrieve internal state

Sources: src/Contracts/Container.php1-189

Method Organization Diagram

Sources: src/Contracts/Container.php1-189

Introspection Methods

These methods query the container's current state without modifying it.

bound()

Determines whether a binding exists for the given abstract type. Returns true if the abstract has been registered via bind(), instance(), or similar methods.

Parameters:

• $abstract: The abstract type identifier (typically a class name or interface name)

Returns: true if binding exists, false otherwise

Sources: src/Contracts/Container.php21-23

has()

PSR-11 compliant method that checks if the container can return an entry for the given identifier. This method returning true guarantees that get($id) will not throw a NotFoundExceptionInterface, though it may throw other exceptions.

Parameters:

• $id: Identifier of the entry to look for (mixed type for PSR-11 compatibility)

Returns: true if the container can provide the entry, false otherwise

Note: This differs from bound() in that it considers both explicit bindings and services that can be auto-resolved.

Sources: src/Contracts/Container.php25-33

resolved()

Determines if the given abstract type has already been resolved at least once. This is useful for checking if a service has been instantiated and potentially cached.

Parameters:

• $abstract: The abstract type identifier

Returns: true if previously resolved, false otherwise

Sources: src/Contracts/Container.php35-38

isAlias()

Checks whether the given name is registered as an alias for another abstract type.

Parameters:

• $name: The potential alias name

Returns: true if the name is an alias, false otherwise

Sources: src/Contracts/Container.php40-43

hasMethodBinding()

Determines if a custom callback has been bound for the specified method via bindMethod().

Parameters:

• $method: Method name in Class@method format or array callable format

Returns: true if method binding exists, false otherwise

Sources: src/Contracts/Container.php55-57

Binding Registration Methods

These methods register services and their resolution strategies with the container.

bind()

Registers a binding with the container. The concrete implementation can be a class name, a closure that returns an instance, or null (in which case the abstract is used as concrete).

Parameters:

• $abstract: The abstract type identifier (interface or class name)
• $concrete: The concrete implementation (class name, Closure, or null)

Throws: TypeError if the concrete parameter is invalid

Sources: src/Contracts/Container.php45-52

bindIf()

Registers a binding only if no binding already exists for the abstract type. This is useful for providing default implementations that can be overridden.

Parameters:

• $abstract: The abstract type identifier
• $concrete: The concrete implementation (class name, Closure, or null)

Sources: src/Contracts/Container.php69-74

instance()

Registers an existing instance as a shared (singleton) service in the container. The instance will be returned for all subsequent resolutions of the abstract type.

Parameters:

• $abstract: The abstract type identifier
• $instance: The pre-instantiated object

Returns: The instance that was registered

Sources: src/Contracts/Container.php83-86

alias()

Creates an alias for an abstract type, allowing it to be resolved by multiple names. The alias will resolve to the same instance as the abstract.

Parameters:

• $abstract: The original abstract type
• $alias: The alias name

Throws: LogicException if the alias creates a circular reference

Sources: src/Contracts/Container.php88-93

bindMethod()

Binds a callback that will be invoked when the specified method is called via Container::call(). This allows custom resolution logic for specific method invocations.

Parameters:

• $method: Method identifier (string in Class@method format or array callable)
• $callback: Closure to execute for this method

Sources: src/Contracts/Container.php59-62

extend()

Registers an extender callback that will be applied to instances after they are resolved. Extenders allow decoration of services without modifying their registration.

Parameters:

• $abstract: The abstract type to extend
• $closure: Extender function receiving ($service, $container) and returning modified service

Throws: InvalidArgumentException if the abstract is not bound

Sources: src/Contracts/Container.php76-81

Resolution Methods

These methods retrieve or instantiate services from the container.

makeWith()

Resolves an abstract type with explicit constructor parameters. This is an alias for make() (inherited from Hyperf) with parameters.

Parameters:

• $abstract: The abstract type to resolve (callable or string)
• $parameters: Associative array of constructor parameters to override autowiring

Returns: The resolved instance

Throws: \Hyperf\Di\Exception\NotFoundException if the abstract cannot be resolved

Sources: src/Contracts/Container.php120-127

call()

Invokes a callable with automatic dependency injection for its parameters. Supports closures, Class@method strings, and callable arrays.

Parameters:

• $callback: Callable or string in Class@method format
• $parameters: Associative array of parameters to override dependency injection
• $defaultMethod: Default method name if callback is a class without method

Returns: The result of the callback invocation

Throws: InvalidArgumentException if callback format is invalid

Sources: src/Contracts/Container.php105-113

factory()

Returns a closure that, when invoked, resolves the given abstract type. This is useful for lazy instantiation or creating factory functions.

Parameters:

• $abstract: The abstract type identifier

Returns: Closure that resolves the abstract type when called

Sources: src/Contracts/Container.php115-118

callMethodBinding()

Invokes a method binding registered via bindMethod(). This is called internally by call() when a method binding exists.

Parameters:

• $method: Method identifier
• $instance: The instance on which the method should be invoked

Returns: The result of the bound callback

Sources: src/Contracts/Container.php64-67

Lifecycle Callback Methods

These methods register callbacks that execute during the service resolution pipeline.

Sources: src/Contracts/Container.php129-148

beforeResolving()

Registers a callback to execute before the container begins resolving a type. If only a closure is provided, it applies globally to all resolutions.

Parameters:

• $abstract: Type-specific abstract (string) or global callback (Closure)
• $callback: Callback function if first parameter is a string (receives $abstract, $parameters, $container)

Sources: src/Contracts/Container.php129-134

resolving()

Registers a callback to execute during resolution, after the instance is created but before it's returned. This is the primary hook for instance decoration.

Parameters:

• $abstract: Type-specific abstract (string) or global callback (Closure)
• $callback: Callback function if first parameter is a string (receives $instance, $container)

Sources: src/Contracts/Container.php136-141

afterResolving()

Registers a callback to execute after resolution is complete, including after all extenders and resolving callbacks.

Parameters:

• $abstract: Type-specific abstract (string) or global callback (Closure)
• $callback: Callback function if first parameter is a string (receives $instance, $container)

Sources: src/Contracts/Container.php143-148

rebinding()

Registers a callback that executes when an abstract type is rebound (re-registered) in the container. Useful for updating dependent services when a binding changes.

Parameters:

• $abstract: The abstract type to watch
• $callback: Callback receiving ($container, $instance)

Returns: Result of immediately invoking the callback if the abstract is already resolved

Sources: src/Contracts/Container.php95-98

refresh()

Refreshes an instance by re-resolving it and calling a method on the target object with the new instance. This enables hot-swapping of dependencies.

Parameters:

• $abstract: Abstract type to re-resolve
• $target: Object to receive the refreshed instance
• $method: Method name on target to invoke with the new instance

Returns: Result of the method invocation

Sources: src/Contracts/Container.php100-103

Container Management Methods

These methods manipulate the container's internal state, removing bindings and clearing caches.

unbind()

Removes a binding from the container, including its alias and resolved instance if present.

Parameters:

• $name: The abstract type or alias to remove

Sources: src/Contracts/Container.php15-18

forgetInstance()

Removes a resolved instance from the instance cache without affecting the binding. The next resolution will create a new instance.

Parameters:

• $abstract: The abstract type whose instance should be forgotten

Sources: src/Contracts/Container.php165-168

forgetInstances()

Clears all resolved instances from the instance cache while preserving all bindings. Useful for testing or memory management.

Sources: src/Contracts/Container.php170-173

forgetExtenders()

Removes all extender callbacks registered for a specific abstract type.

Parameters:

• $abstract: The abstract type whose extenders should be removed

Sources: src/Contracts/Container.php160-163

flush()

Completely resets the container by removing all bindings, instances, aliases, callbacks, and extenders. This returns the container to its initial state.

Sources: src/Contracts/Container.php175-178

Accessor Methods

These methods provide read-only access to the container's internal state.

getBindings()

Returns the complete array of registered bindings. Useful for introspection and debugging.

Returns: Associative array where keys are abstract types and values are binding configurations

Sources: src/Contracts/Container.php150-153

getAlias()

Resolves an abstract type through any alias chain to its final abstract name.

Parameters:

• $abstract: The abstract type or alias

Returns: The final abstract name after resolving all aliases

Sources: src/Contracts/Container.php155-158

Static Container Access

The interface defines static methods for managing a global singleton container instance.

getInstance()

Retrieves the globally available container instance. This enables static access patterns and facade implementations.

Returns: The shared container instance

Sources: src/Contracts/Container.php180-183

setInstance()

Sets the global container instance. This is typically called during application bootstrap.

Parameters:

• $container: The container instance to set as global

Returns: The container instance that was set

Sources: src/Contracts/Container.php185-188

PSR-11 Compliance

The interface maintains PSR-11 compliance through its inheritance chain:

Standard	Method	Source	Purpose
PSR-11	has($id): bool	Overridden in this interface	Check entry availability
PSR-11	get($id): mixed	Inherited from Hyperf	Retrieve entry
PSR-11 Exception	NotFoundExceptionInterface	Thrown by get()	Entry not found error
PSR-11 Exception	ContainerExceptionInterface	Base for all exceptions	General container errors

The has() method is explicitly redeclared in this interface src/Contracts/Container.php25-33 with enhanced documentation to clarify PSR-11 semantics, while get() is inherited from HyperfContainerInterface.

Sources: src/Contracts/Container.php13 src/Contracts/Container.php25-33

Method Summary Table

Method	Category	Return Type	Mutates State	Throws Exceptions
bound()	Introspection	bool	No	No
has()	Introspection	bool	No	No
resolved()	Introspection	bool	No	No
isAlias()	Introspection	bool	No	No
hasMethodBinding()	Introspection	bool	No	No
bind()	Binding	void	Yes	TypeError
bindIf()	Binding	void	Yes (conditional)	No
instance()	Binding	mixed	Yes	No
alias()	Binding	void	Yes	LogicException
bindMethod()	Binding	void	Yes	No
extend()	Binding	void	Yes	InvalidArgumentException
makeWith()	Resolution	mixed	No	NotFoundException
call()	Resolution	mixed	No	InvalidArgumentException
factory()	Resolution	Closure	No	No
callMethodBinding()	Resolution	mixed	No	No
beforeResolving()	Lifecycle	void	Yes	No
resolving()	Lifecycle	void	Yes	No
afterResolving()	Lifecycle	void	Yes	No
rebinding()	Lifecycle	mixed	Yes	No
refresh()	Lifecycle	mixed	Yes	No
unbind()	Management	void	Yes	No
forgetInstance()	Management	void	Yes	No
forgetInstances()	Management	void	Yes	No
forgetExtenders()	Management	void	Yes	No
flush()	Management	void	Yes	No
getBindings()	Accessor	array	No	No
getAlias()	Accessor	string	No	No
getInstance()	Static	Container	No	No
setInstance()	Static	Container	Yes	No

Sources: src/Contracts/Container.php1-189