VOOZH about

URL: https://deepwiki.com/hypervel/components/6-cache-system

⇱ Cache System | hypervel/components | DeepWiki

Loading...
Loading...
Last indexed: 7 March 2026 (96fbab)
Menu

Cache System

Purpose and Scope

The Cache System provides a flexible, multi-tier caching architecture for Hypervel applications. It supports multiple cache drivers including Swoole Table-based in-memory storage, Redis, file-based caching, and layered cache stacks. The system is designed to work efficiently in Swoole's coroutine environment while maintaining Laravel-compatible APIs.

This document covers cache driver management, store implementations, and multi-tier caching strategies. For queue-based job processing that may interact with cached data, see Queue System and Job Processing.

Sources: src/cache/src/CacheManager.php1-335

Architecture Overview

The cache system consists of three primary layers: the CacheManager that resolves and instantiates cache stores, the individual Store implementations that handle actual data storage, and the Repository pattern that provides the public API for cache operations.



Sources: src/cache/src/CacheManager.php25-335 src/cache/src/SwooleStore.php14-372 src/cache/src/StackStore.php11-184




Cache Manager and Driver Resolution


The CacheManager class acts as a factory for cache stores, resolving driver names to concrete store implementations. It maintains a registry of resolved stores and supports custom driver registration.


Driver Resolution Flow




Sources: src/cache/src/CacheManager.php56-191


Key Methods































MethodPurpose
store(?string $name)Retrieve a cache store by name, returns cached instance if available
repository(Store $store, array $config)Wrap a store in a Repository with optional event dispatcher
extend(string $driver, Closure $callback)Register custom driver creator
forgetDriver(array|string|null $name)Clear cached store instance
getDefaultDriver()Get default driver from cache.default config


Sources: src/cache/src/CacheManager.php56-148


Built-in Driver Creation


The manager provides factory methods for each supported driver:



Sources: src/cache/src/CacheManager.php204-300




Swoole Store - In-Memory Caching


The SwooleStore provides high-performance in-memory caching using Swoole Table, a shared memory data structure that is safe for use across coroutines. It implements sophisticated memory management with configurable eviction policies.


Memory Management Architecture




Sources: src/cache/src/SwooleStore.php45-372


Eviction Policies


The SwooleStore supports four eviction policies configured via the eviction_policy option:
































PolicyConstantBehavior
LRUEVICTION_POLICY_LRUEvicts least recently used items based on last_used_at timestamp
LFUEVICTION_POLICY_LFUEvicts least frequently used items based on used_count counter
TTLEVICTION_POLICY_TTLEvicts items with shortest remaining TTL based on expiration timestamp
No EvictionEVICTION_POLICY_NOEVICTIONDoes not evict items when memory limit reached


Sources: src/cache/src/SwooleStore.php16-22 src/cache/src/SwooleStore.php298-317


Memory Limit Detection


The store monitors memory usage using two metrics:


    

  1. Conflict Rate: 1 - (available_slice_num / total_slice_num) - indicates hash table collision rate
    2. 

  2. Memory Usage: num / table_size - indicates how full the table is
    3. 



When either metric exceeds 1 - memory_limit_buffer, eviction is triggered. The eviction_proportion config determines what percentage of entries to remove during eviction.


Sources: src/cache/src/SwooleStore.php288-296 src/cache/src/SwooleStore.php334-354


Interval Caching


Interval caching allows cache keys to be automatically refreshed at specified intervals without manual invalidation:




The interval metadata is stored with the following structure:


    

  • resolver: SerializableClosure that generates the value
    • 

  • lastRefreshedAt: Timestamp of last refresh
    • 

  • refreshInterval: Seconds between refreshes
    • 



Sources: src/cache/src/SwooleStore.php161-204


Swoole Table Configuration


The SwooleTableManager creates and configures Swoole Tables with the required columns:
































ColumnTypePurpose
valueTYPE_STRINGSerialized cache value
expirationTYPE_FLOATExpiration timestamp with microseconds
last_used_atTYPE_FLOATLast access timestamp for LRU
used_countTYPE_INTAccess counter for LFU


Sources: src/cache/src/SwooleTableManager.php21-33




Stack Store - Multi-Tier Caching


The StackStore implements a layered caching strategy where multiple cache stores work together as a single logical cache. Cache misses in faster layers are automatically restored from slower layers (cache promotion).


Multi-Tier Read Flow




Sources: src/cache/src/StackStore.php107-127


Write-Through Pattern


All write operations propagate through all layers. If any layer fails, previous layers are rolled back:




Sources: src/cache/src/StackStore.php129-135 src/cache/src/StackStore.php165-183


Record Structure


The StackStore normalizes cache records across layers using a consistent structure:




When restoring from a deeper layer to a shallower layer, the TTL is recalculated to account for time elapsed since the record was originally stored.


Sources: src/cache/src/StackStore.php137-154


Stack Store Proxy and Per-Layer TTL


The StackStoreProxy wraps individual stores to enforce maximum TTL limits per layer. This is useful for limiting how long data stays in fast but limited-capacity stores:




When a put() operation is called with a TTL exceeding the proxy's maxTTL, the proxy substitutes the maximum TTL instead. This ensures items don't stay in memory caches longer than desired.


Sources: src/cache/src/StackStoreProxy.php10-82 src/cache/src/CacheManager.php268-277


Configuration Example


A stack store is configured by specifying an ordered list of stores from fastest to slowest:




Sources: tests/Cache/CacheStackStoreTest.php374-420




Cache Operations and TTL Management


Timestamp Precision


The SwooleStore uses microsecond-precision timestamps to handle sub-second TTLs accurately:




This allows cache items to expire at precise sub-second intervals, which is tested in tests/Cache/CacheSwooleStoreTest.php196-210


Sources: src/cache/src/SwooleStore.php280-283


Usage Tracking


When a cache item is retrieved via get(), the SwooleStore updates usage statistics for eviction algorithms:


    

  1. last_used_at is set to current timestamp (for LRU)
    2. 

  2. used_count is incremented (for LFU)
    3. 



Sources: src/cache/src/SwooleStore.php261-275


Forever Storage


The forever() method stores items with a TTL of one year (31536000 seconds). This is effectively permanent for Swoole's in-memory table:


Sources: src/cache/src/SwooleStore.php24 src/cache/src/SwooleStore.php153-156




Limited Max Heap for Eviction


The LimitedMaxHeap class extends PHP's SplMaxHeap to maintain a fixed-size priority queue for eviction algorithms. When the heap reaches its limit, it only inserts new items if they have lower priority than the current top element.


This is used during eviction to select which records to remove. For example, in LRU eviction:


    

  1. A heap is created with size equal to eviction_proportion * table_size
    2. 

  2. All records are iterated and their last_used_at values inserted
    3. 

  3. The heap maintains only the records with the oldest last_used_at timestamps
    4. 

  4. These records are then removed from the table
    5. 



Sources: src/cache/src/LimitedMaxHeap.php9-30 src/cache/src/SwooleStore.php334-354




Repository Pattern


The Repository class wraps a Store implementation to provide the public cache API. It adds features like:


    

  • Event dispatching for cache hits/misses/writes
    • 

  • Tag support (when store implements TaggableStore)
    • 

  • Lock provider support
    • 

  • Convenience methods for common patterns
    • 



The CacheManager::repository() method creates Repository instances and optionally configures event dispatching based on the events configuration option.


Sources: src/cache/src/CacheManager.php74-93




Swoole Table Size Validation


The custom SwooleTable class extends Swoole's Table to validate that string values don't exceed configured column sizes:




This prevents silent data truncation that would occur with the standard Swoole Table implementation.


Sources: src/cache/src/SwooleTable.php23-63 src/cache/src/Exceptions/ValueTooLargeForColumnException.php1-11




Configuration Structure


The cache system is configured via config/cache.php with the following structure:



































Configuration KeyPurpose
cache.defaultDefault cache driver name
cache.prefixGlobal cache key prefix
cache.stores.{name}Configuration for individual store
cache.stores.{name}.driverDriver type (redis, swoole, stack, etc.)
cache.stores.{name}.eventsEnable event dispatching for this store
cache.swoole_tables.{name}Swoole table dimensions configuration


Sources: src/cache/src/CacheManager.php98-334 src/cache/src/SwooleTableManager.php40-62