 |
VOOZH | about |
|
VOOZH | about |
This document describes the configuration callback mechanism provided by the Repository class that allows applications to register reactive handlers that execute automatically after configuration values are modified. This enables patterns such as cache invalidation, event broadcasting, or configuration validation that need to respond to configuration changes at runtime.
For information about basic configuration reading and writing operations, see Repository Class. For information about array manipulation operations that also trigger callbacks, see Type-Safe Configuration Access.
Sources: src/Repository.php1-255
The callback mechanism is implemented through a static closure property in the Repository class that, when registered, is automatically invoked after any call to the set() method. This provides a centralized hook point for reacting to configuration changes without requiring modifications to calling code.
The system supports a single global callback that receives information about all modified keys, making it suitable for operations that need to track all configuration changes in one location.
Sources: src/Repository.php19-21 src/Repository.php207-213
The Repository class provides the afterSettingCallback() method to register or clear the callback:
This method accepts either a Closure to register a new callback or null to clear any existing callback. The callback is stored in the static property $afterSettingCallback.
Key Characteristics:
| Property | Description |
|---|---|
| Scope | Static - shared across all Repository instances |
| Storage | Repository::$afterSettingCallback property |
| Signature | Closure or null |
| Registration | Via afterSettingCallback() method |
| Replacement | Each call replaces the previous callback |
Sources: src/Repository.php19-21 src/Repository.php207-213
The registered callback is invoked automatically by the set() method after modifying configuration values. All operations that modify configuration ultimately flow through set(), ensuring consistent callback behavior.
Diagram: Configuration Callback Execution Flow
Sources: src/Repository.php162-173 src/Repository.php176-197 src/Repository.php238-243
The callback receives a single parameter: an associative array containing all keys that were modified during the set() operation. The array structure is:
Parameter Details:
| Aspect | Description |
|---|---|
| Parameter Count | 1 |
| Parameter Type | array<string, mixed> |
| Key Format | Dot-notation configuration keys |
| Value Format | The new values that were set |
| Batch Support | Multiple keys if set() was called with an array |
The callback invocation occurs after all values have been set using Arr::set():
Sources: src/Repository.php164-172
Diagram: Callback Component Structure
Sources: src/Repository.php14-255
The most common use case is invalidating caches when configuration changes:
Track all configuration modifications for audit purposes:
Broadcast configuration changes to other parts of the system:
Perform post-modification validation:
Sources: src/Repository.php207-213
The callback is stored in a static property, which has specific implications:
| Characteristic | Implication |
|---|---|
| Shared State | All Repository instances share the same callback |
| Persistence | Callback persists across multiple repository instances |
| Single Callback | Only one callback can be registered at a time |
| Global Scope | Affects all configuration changes application-wide |
Since Hyperf applications may run in Swoole coroutine contexts:
Sources: src/Repository.php19-21
Diagram: Methods That Trigger Callbacks
Methods Summary:
| Method | Lines | Triggers Callback | Notes |
|---|---|---|---|
set() | 162-173 | Yes | Primary modification method |
prepend() | 178-185 | Yes | Calls set() internally |
push() | 190-197 | Yes | Calls set() internally |
offsetSet() | 241-243 | Yes | ArrayAccess interface, calls set() |
get() | 41-48 | No | Read-only operation |
has() | 33-36 | No | Read-only operation |
offsetUnset() | 251-254 | Yes | Sets value to null via set() |
Sources: src/Repository.php162-173 src/Repository.php176-197 src/Repository.php238-254
To stop callback execution, pass null to the afterSettingCallback() method:
After clearing, subsequent set() operations will not trigger any callback until a new one is registered.
The callback is only invoked if it is not null:
This check occurs on every set() operation, ensuring efficient no-op behavior when no callback is registered.
Sources: src/Repository.php170-172 src/Repository.php207-213
The Repository class implements ArrayAccess, allowing array-style configuration modification:
The offsetSet() method delegates to set(), ensuring callbacks are triggered:
Similarly, offsetUnset() triggers callbacks by calling set() with null:
Sources: src/Repository.php238-254
When set() is called with an array of keys, the callback receives all modified keys:
This enables efficient batch processing in the callback rather than handling each key individually.
The set() method processes all keys in a loop before invoking the callback:
Sources: src/Repository.php164-172
Only one callback can be registered at a time. Registering a new callback replaces the previous one:
Workaround Pattern:
To support multiple behaviors, compose them within a single callback:
The callback system only triggers on write operations (set() and related methods). Read operations (get(), has()) do not trigger callbacks.
Exceptions thrown within the callback will propagate to the caller of set():
Consider implementing error handling within the callback to prevent disrupting configuration updates.
Sources: src/Repository.php19-21 src/Repository.php162-173 src/Repository.php207-213
The configuration callback mechanism provides a centralized, reactive pattern for responding to configuration changes. Key points:
| Aspect | Details |
|---|---|
| Registration | Via afterSettingCallback(?Closure $callback) |
| Storage | Static property shared across all instances |
| Trigger | Automatic on set(), prepend(), push(), offsetSet(), offsetUnset() |
| Parameters | Array of modified keys and their new values |
| Limitation | Single callback only; replaces previous registration |
| Use Cases | Cache invalidation, logging, event broadcasting, validation |
The mechanism integrates seamlessly with all configuration modification operations, including array access syntax, ensuring consistent behavior regardless of how configuration is updated.
Sources: src/Repository.php1-255
Refresh this wiki