 |
VOOZH | about |
|
VOOZH | about |
This document covers the global helper function provided by the hypervel/cache package for simplified cache access. The cache() helper provides a convenient, polymorphic API for interacting with the cache system without requiring explicit dependency injection. For information about the underlying CacheManager factory, see 2.1. For details about the Repository interface used by the helper, see 2.2.
The cache() helper function provides a polymorphic API with three operational modes determined by parameter types: factory access (null), cache retrieval (string key), and cache storage (array). The function leverages PHPDoc conditional return types for static analysis support.
The cache() function serves as a polymorphic gateway to the cache system, changing its behavior based on the arguments provided.
The function is defined in src/Functions.php21-40 with the following signature:
The function accepts two parameters:
$key: Can be null, a string (cache key), or an array (key-value pairs for storage)$default: Can be a default value (for retrieval), TTL in seconds (for storage), or nullSources: src/Functions.php21-22
Diagram: cache() Function Control Flow with Method Calls
Sources: src/Functions.php25-40
| Condition | Code Check | Method Call | Return Type |
|---|---|---|---|
| No arguments | is_null($key) | Return $manager | CacheManager |
| String key | is_string($key) | $manager->get($key, $default) | mixed |
| Array data | is_array($key) | $manager->put(key($key), reset($key), $default) | bool |
| Invalid type | !is_array($key) | Throw InvalidArgumentException | Never returns |
Sources: src/Functions.php25-40
<old_str>
src/Functions.php23 retrieves the CacheManager singleton from Hyperf's container:
This design ensures the helper accesses the same configured CacheManager instance used by dependency-injected components, maintaining consistency across the application.
Sources: src/Functions.php7-23 </old_str> <new_str>
Diagram: cache() Function Execution Flow with Actual Methods
Sources: src/Functions.php21-40 </old_str>
<old_str>
src/Functions.php23 retrieves the container using Hyperf's ApplicationContext:
This approach ensures the helper function:
Sources: src/Functions.php7-23
<old_str>
src/Functions.php23 retrieves the container using Hyperf's ApplicationContext:
This approach ensures the helper function:
Sources: src/Functions.php7-23
When called without arguments, cache() returns the CacheManager instance, allowing direct access to the factory for advanced operations.
src/Functions.php23-26 retrieves the CacheManager from the application container and returns it directly when $key is null:
| Code | Description | Return Type |
|---|---|---|
cache() | Get the CacheManager instance | CacheManager |
cache()->store('redis') | Get a specific store | Repository |
cache()->driver('file') | Alias for getting a store | Repository |
cache()->getDefaultDriver() | Get default driver name | string |
This mode enables access to all CacheManager methods documented in 2.1, including store selection, custom driver registration, and configuration management.
Sources: src/Functions.php23-26
When called with a string key, cache() retrieves a value from the default cache store.
src/Functions.php29-30 performs a GET operation on the default store:
The CacheManager::get() method delegates to the default store's Repository, which is covered in 2.2.
| Code | Description | Return Value |
|---|---|---|
cache('user:123') | Retrieve value, return null if missing | mixed or null |
cache('user:123', []) | Retrieve value, return [] if missing | mixed or [] |
cache('config', fn() => loadConfig()) | Retrieve or execute closure and cache | mixed |
The $default parameter accepts:
remember() pattern (see 2.2)null: Standard behavior, returns null for cache missesSources: src/Functions.php29-30
When called with an array as the first argument, cache() stores a key-value pair in the default cache store.
src/Functions.php33-39 extracts the key and value from the array and performs a PUT operation:
The implementation uses:
key($key): Extracts the first key from the arrayreset($key): Extracts the first value from the array$default: Interpreted as TTL (time-to-live) in seconds| Code | Description | TTL |
|---|---|---|
cache(['user:123' => $user]) | Store indefinitely (forever) | Forever |
cache(['user:123' => $user], 3600) | Store for 1 hour | 3600 seconds |
cache(['token' => $jwt], 60) | Store for 1 minute | 60 seconds |
cache(['temp' => $data], null) | Store indefinitely | Forever |
The function returns bool indicating success or failure of the PUT operation.
Sources: src/Functions.php33-39
The helper function validates input types at runtime to ensure type safety beyond PHP's type system.
src/Functions.php33-37 throws an InvalidArgumentException if the first argument is not null, a string, or an array:
This validation ensures that the polymorphic behavior is predictable and prevents silent failures from incorrect usage.
Sources: src/Functions.php8-37
The function uses advanced PHPDoc annotations to provide IDE autocompletion and static analysis support.
src/Functions.php17 declares conditional return types based on parameter types:
This annotation tells static analysis tools:
$key is null, return type is CacheManager$key is a string, return type is mixed (retrieved value)bool (success indicator)src/Functions.php15-16 documents the dual purpose of parameters:
This notation indicates that parameter semantics change based on the operation mode.
Sources: src/Functions.php15-17
The helper function integrates with Hyperf's dependency injection container to access the cache system.
Sources: src/Functions.php23
src/Functions.php23 retrieves the container using Hyperf's ApplicationContext:
This approach ensures the helper function:
Sources: src/Functions.php7-23
The helper function provides a convenient alternative to direct dependency injection, with tradeoffs to consider.
| Aspect | Helper Function | Direct Injection |
|---|---|---|
| Syntax | cache('key') | $cache->get('key') |
| DI Container | Implicit access | Explicit dependency |
| Testability | Harder to mock | Easy to mock |
| Type Safety | PHPDoc-based | Native PHP types |
| Store Selection | Via factory mode | Constructor parameter |
| Code Length | Shorter | More verbose |
The cache() helper is ideal for:
Direct CacheManager or Repository injection is preferred for:
Sources: src/Console/ClearCommand.php58-62 (example of direct injection)
The ClearCommand demonstrates practical usage patterns for accessing the cache system.
Diagram: ClearCommand Cache Access Pattern
src/Console/ClearCommand.php56-62 demonstrates explicit container resolution:
Method call sequence:
$this->app->get(CacheContract::class) - Resolves CacheManager from container->store($this->argument('store')) - Selects named store (defaults to configured driver)->tags($this->tags()) - Optionally applies tag filtering for tagged operationsThis explicit pattern provides better testability than the global cache() helper by allowing mock injection of CacheContract.
Sources: src/Console/ClearCommand.php56-62
The cache() helper function provides three operational modes accessed through a single polymorphic interface:
| Mode | Call Pattern | Purpose | Return Type |
|---|---|---|---|
| Factory | cache() | Access CacheManager | CacheManager |
| Retrieval | cache(string, mixed) | Get cached value | mixed |
| Storage | cache(array, int) | Put value with TTL | bool |
The helper simplifies common cache operations while maintaining access to the full power of the CacheManager factory and Repository facade patterns documented in sections 2.1 and 2.2.
Sources: src/Functions.php1-41
Refresh this wiki