Lifecycle Callbacks

Purpose and Scope

This page documents the container's lifecycle callback system, which allows code to hook into various stages of the dependency resolution process. The container provides four types of callbacks: before resolving, resolving, after resolving, and rebound callbacks. Each type serves different purposes in monitoring and modifying service instantiation.

For information about extenders (which modify resolved instances), see Extenders, Aliases & Method Bindings. For the overall dependency resolution process, see Dependency Resolution.

---

Callback Types Overview

The container supports four distinct callback types that execute at different points in the service lifecycle:

Callback Type	Execution Point	Primary Use Case
Before Resolving	Before instantiation begins	Modify parameters, add bindings, prepare environment
Resolving	After instantiation, before extenders	Inspect or modify the instance, perform setup
After Resolving	After extenders applied	Final modifications, logging, event firing
Rebound	When a binding is replaced	Update dependent instances, refresh state

Sources: src/Container.php56-94 src/Contracts/Container.php130-148

---

Resolution Pipeline Integration

The following diagram illustrates how callbacks integrate into the service resolution pipeline:

Diagram: Callback Execution in the Resolution Process

Sources: src/Container.php109-132 src/Container.php243-259 src/Container.php329-349

---

Global vs Type-Specific Callbacks

Callbacks can be registered globally (for all types) or for specific types. The registration method signature determines which category the callback belongs to:

Registration Patterns

Global callback (applies to all types):
 beforeResolving(Closure $callback)
 resolving(Closure $callback)
 afterResolving(Closure $callback)

Type-specific callback (applies to one type):
 beforeResolving(string $abstract, Closure $callback)
 resolving(string $abstract, Closure $callback)
 afterResolving(string $abstract, Closure $callback)

Storage Structure

Storage Array	Purpose	Location
globalBeforeResolvingCallbacks	Global before callbacks	src/Container.php59
beforeResolvingCallbacks	Type-specific before callbacks	src/Container.php80
globalResolvingCallbacks	Global resolving callbacks	src/Container.php66
resolvingCallbacks	Type-specific resolving callbacks	src/Container.php87
globalAfterResolvingCallbacks	Global after callbacks	src/Container.php73
afterResolvingCallbacks	Type-specific after callbacks	src/Container.php94
reboundCallbacks	Type-specific rebound callbacks	src/Container.php52

Sources: src/Container.php56-94

---

Before Resolving Callbacks

Before resolving callbacks execute before the container begins instantiating a service. They receive the abstract name and parameters, allowing modification of the resolution environment.

Method: beforeResolving()

beforeResolving(Closure $callback): void // Global
beforeResolving(string $abstract, Closure $callback): void // Type-specific

Implementation: src/Container.php467-478

Callback Signature

Execution Logic

The method fireBeforeResolvingCallbacks() executes callbacks in this order:

1. All global before callbacks
2. Type-specific callbacks where the type matches exactly
3. Type-specific callbacks where the abstract is a subclass of the registered type

Sources: src/Container.php522-544

---

Resolving Callbacks

Resolving callbacks execute after instantiation but during the resolution process, before after-resolving callbacks. They receive the resolved instance.

Method: resolving()

resolving(Closure $callback): void // Global
resolving(string $abstract, Closure $callback): void // Type-specific

Implementation: src/Container.php485-496

Callback Signature

Execution Context

Resolving callbacks execute within fireResolvingCallbacks(), which is called from make() after extenders are applied:

Sources: src/Container.php129 src/Container.php552-562

---

After Resolving Callbacks

After resolving callbacks execute at the end of the resolution pipeline, after all extenders and resolving callbacks have run. This is the final hook before the instance is returned.

Method: afterResolving()

afterResolving(Closure $callback): void // Global
afterResolving(string $abstract, Closure $callback): void // Type-specific

Implementation: src/Container.php503-514

Callback Signature

Execution Sequence

The method fireAfterResolvingCallbacks() is called from within fireResolvingCallbacks():

1. Global after callbacks execute first
2. Type-specific callbacks execute for matching types (exact match or instanceof)

Sources: src/Container.php570-578 src/Container.php561

---

Type Matching for Callbacks

The following diagram shows how the container determines which type-specific callbacks to execute:

Diagram: Type-Specific Callback Matching Logic

Sources: src/Container.php526-530 src/Container.php587-598

---

Rebound Callbacks

Rebound callbacks execute when a service binding is replaced after it has already been bound. This allows dependent code to refresh references to the service.

Method: rebinding()

rebinding(string $abstract, Closure $callback): mixed

Implementation: src/Container.php388-397

Callback Signature

When Rebound Fires

The rebound() method is called in these scenarios:

1. bind() is called for an already-bound abstract src/Container.php254-256
2. extend() is called for an already-resolved abstract src/Container.php320
3. instance() is called for an already-bound abstract src/Container.php342-344

Method: refresh()

The refresh() method is a convenience wrapper around rebinding() that automatically calls a method on a target object when the abstract is rebound:

refresh(string $abstract, mixed $target, string $method): mixed

Implementation: src/Container.php402-407

Sources: src/Container.php388-419

---

Callback Execution Order

The following table summarizes the complete execution order during service resolution:

Order	Stage	Method Called	Callbacks Executed
1	Pre-resolution	fireBeforeResolvingCallbacks()	Global before → Type-specific before
2	Instantiation	parent::make()	(Hyperf instantiation logic)
3	Extension	Loop through extenders	Extender closures
4	Resolution	fireResolvingCallbacks()	Global resolving → Type-specific resolving
5	Post-resolution	fireAfterResolvingCallbacks()	Global after → Type-specific after

Sources: src/Container.php109-132

---

Internal Storage and Retrieval

The following diagram maps callback registration methods to internal storage arrays:

Diagram: Callback Storage and Retrieval Flow

Sources: src/Container.php467-514 src/Container.php522-578 src/Container.php388-427

---

Helper Methods for Callback Execution

fireBeforeCallbackArray()

Executes an array of before callbacks with the abstract name and parameters:

Implementation: src/Container.php539-544

fireCallbackArray()

Executes an array of resolving/after callbacks with the resolved object:

Implementation: src/Container.php605-610

getCallbacksForType()

Retrieves all callbacks that match the given abstract/object by exact match or instanceof:

Implementation: src/Container.php587-598

getReboundCallbacks()

Retrieves rebound callbacks for a specific abstract:

Implementation: src/Container.php424-427

Sources: src/Container.php424-427 src/Container.php539-544 src/Container.php587-610

---

Use Cases and Examples

Use Case: Logging Service Resolution

Before callbacks can log when services are being resolved:

Use Case: Automatic Property Injection

Resolving callbacks can inject properties after instantiation:

Use Case: Event Broadcasting

After callbacks can broadcast events after services are fully resolved:

Use Case: Maintaining Singleton References

Rebound callbacks ensure dependent objects receive updated instances:

Sources: src/Container.php467-514 src/Container.php388-407

---

Alias Resolution in Callbacks

When registering callbacks with string abstracts, the container automatically resolves aliases:

The alias resolution occurs in all three registration methods via getAlias():

Sources: src/Container.php469-470 src/Container.php487-488 src/Container.php505-506 src/Container.php623-628

---

Interface Declaration

The container contract defines the public API for callback registration:

Method	Declaration Location
beforeResolving()	src/Contracts/Container.php134
resolving()	src/Contracts/Container.php141
afterResolving()	src/Contracts/Container.php148
rebinding()	src/Contracts/Container.php98
refresh()	src/Contracts/Container.php103

Sources: src/Contracts/Container.php98-148

---

Summary Table: Callback Characteristics

Characteristic	Before Resolving	Resolving	After Resolving	Rebound
Receives instance	No	Yes	Yes	Yes
Can modify parameters	Yes (via closure)	No	No	No
Execution point	Pre-instantiation	Post-instantiation	Post-extenders	On rebind
Global support	Yes	Yes	Yes	No
Type-specific support	Yes	Yes	Yes	Yes
Subclass matching	Yes	Yes	Yes	No
Return value	None	None	None	Mixed (instance if bound)

Sources: src/Container.php467-514 src/Container.php522-578 src/Container.php388-419