Architecture Overview

This document provides a high-level overview of the hypervel/cache system architecture, explaining how the core components interact and how cache operations flow through the system. It covers the layered architecture, factory pattern, store abstraction, and the plugin-based design that enables multiple backend implementations.

For installation and configuration details, see Installation and Configuration. For in-depth documentation on individual components, see Core Components and Cache Stores.

System Layers

The cache system is organized into distinct architectural layers, each with specific responsibilities. This separation enables flexibility, testability, and extensibility.

Sources: src/CacheManager.php25-335 src/Repository.php37-734 src/Contracts/Store.php src/Contracts/Factory.php

Client Layer

The Client Layer provides entry points for application code to interact with the cache system:

• Application Code: Direct usage of cache operations via the CacheManager or Repository instances
• cache() Helper Function: Global helper defined in src/Functions.php for convenient access
• Console Commands: Administrative tools like cache:clear and cache:prune-db-expired for cache management

Orchestration Layer

The Orchestration Layer contains two critical components:

Component	Responsibility	Key Methods
CacheManager	Factory for creating and caching Repository instances	store(), driver(), extend()
Repository	Unified cache API with event dispatching and convenience methods	get(), put(), remember(), forget()

The CacheManager src/CacheManager.php25-335 acts as the central factory, resolving configuration and creating appropriate store instances wrapped in Repository objects. It implements lazy loading and caches resolved instances in src/CacheManager.php30

The Repository src/Repository.php37-734 provides a consistent API across all store implementations, handling serialization, event dispatching, and convenience patterns like remember() and type-safe getters.

Storage Backend Layer

The Storage Backend Layer consists of seven store implementations, all conforming to the Store interface contract src/Contracts/Store.php Each store provides a different persistence strategy:

• ArrayStore: In-memory storage for testing
• FileStore: Filesystem-based persistence
• DatabaseStore: SQL-backed storage
• RedisStore: Distributed caching via Redis
• SwooleStore: Shared memory using Swoole tables
• StackStore: Multi-tier caching combining multiple stores
• NullStore: No-op implementation for disabling cache

Infrastructure Layer

The Infrastructure Layer provides framework integration and external dependencies:

• EventDispatcherInterface: PSR-14 event dispatcher for cache lifecycle events
• ConfigInterface: Hyperf configuration system access
• ContainerInterface: PSR-11 dependency injection container
• RedisFactory: Connection factory for Redis operations
• ConnectionResolverInterface: Database connection resolver
• SwooleTableManager: Manages Swoole table instances

Sources: src/CacheManager.php8-15 src/Repository.php32 src/SwooleTableManager.php

Core Component Relationships

The following diagram illustrates how CacheManager, Repository, and Store implementations relate to each other in code.

Sources: src/CacheManager.php25 src/Repository.php37 src/Contracts/Factory.php src/Contracts/Repository.php src/Contracts/Store.php src/Contracts/LockProvider.php

CacheManager: The Factory

CacheManager src/CacheManager.php25-335 implements the Factory pattern, responsible for:

1. Store Resolution: Reading configuration via getConfig() src/CacheManager.php327-334
2. Driver Creation: Invoking driver-specific factory methods like createRedisDriver() src/CacheManager.php233-245
3. Instance Caching: Storing resolved repositories in $stores array src/CacheManager.php30 to avoid redundant instantiation
4. Custom Driver Registration: Supporting extensibility via extend() src/CacheManager.php142-147

The manager delegates to driver-specific factory methods:

• createArrayDriver() src/CacheManager.php204-207
• createFileDriver() src/CacheManager.php212-220
• createRedisDriver() src/CacheManager.php233-245
• createSwooleDriver() src/CacheManager.php250-261
• createStackDriver() src/CacheManager.php266-280
• createDatabaseDriver() src/CacheManager.php285-300
• createNullDriver() src/CacheManager.php225-228

Repository: The Unified API

Repository src/Repository.php37-734 wraps a Store instance and provides:

1. Unified Cache Operations: Methods like get(), put(), remember(), forget()
2. Event Dispatching: Emits events before and after cache operations src/Repository.php124-140
3. Type-Safe Getters: Methods like string(), integer(), boolean(), array() src/Repository.php570-665
4. Convenience Patterns: remember() src/Repository.php341-355 rememberForever() src/Repository.php380-394

The Repository stores the underlying Store implementation in src/Repository.php47 and delegates storage operations while adding cross-cutting concerns.

Store: The Plugin Contract

The Store interface defines the contract all storage backends must implement:

interface Store {
 public function get(string $key): mixed;
 public function put(string $key, mixed $value, int $seconds): bool;
 public function increment(string $key, int $value = 1): bool|int;
 public function decrement(string $key, int $value = 1): bool|int;
 public function forever(string $key, mixed $value): bool;
 public function forget(string $key): bool;
 public function flush(): bool;
 public function getPrefix(): string;
}

This contract enables polymorphic behavior where any store implementation can be used interchangeably through the same API.

Sources: src/Contracts/Store.php src/CacheManager.php172-191 src/Repository.php66-71

Request Flow

The following sequence diagram shows how cache operations flow through the system from client code to storage backend.

Cache Write Flow

Sources: src/CacheManager.php56-61 src/CacheManager.php172-191 src/Repository.php191-217

Cache Read Flow

Sources: src/Repository.php118-140 src/Repository.php670-687

Remember Pattern Flow

The remember() method combines read and write operations with lazy evaluation:

Sources: src/Repository.php341-355

Store Creation and Configuration

The CacheManager uses configuration-driven factory methods to instantiate stores. Each driver type has a corresponding createXxxDriver() method.

Configuration Resolution

When store($name) is called src/CacheManager.php56-61 the manager:

1. Checks if the store is already cached in $stores[$name] src/CacheManager.php60
2. If not cached, calls resolve($name) src/CacheManager.php172-191
3. Retrieves configuration via getConfig($name) src/CacheManager.php327-334
4. Determines the driver type from $config['driver']
5. Invokes the appropriate factory method or custom creator
6. Wraps the store in a Repository via repository() src/CacheManager.php74-81
7. Configures event dispatcher if enabled src/CacheManager.php305-314
8. Caches the repository instance src/CacheManager.php60

Driver Factory Methods

Each store type has a dedicated factory method:

Driver	Factory Method	Configuration Keys
Redis	createRedisDriver() src/CacheManager.php233-245	connection, lock_connection, prefix
Database	createDatabaseDriver() src/CacheManager.php285-300	connection, table, lock_table, prefix
Swoole	createSwooleDriver() src/CacheManager.php250-261	table, memory_limit_buffer, eviction_policy
File	createFileDriver() src/CacheManager.php212-220	path, permission, lock_path
Stack	createStackDriver() src/CacheManager.php266-280	stores[] with per-store ttl
Array	createArrayDriver() src/CacheManager.php204-207	serialize
Null	createNullDriver() src/CacheManager.php225-228	(none)

Example: Redis Store Creation

The createRedisDriver() method src/CacheManager.php233-245 demonstrates the typical factory pattern:

This method:

1. Resolves the RedisFactory from the container src/CacheManager.php235
2. Extracts connection name from config src/CacheManager.php237
3. Creates RedisStore with prefix src/CacheManager.php239
4. Configures lock connection src/CacheManager.php242
5. Wraps in Repository src/CacheManager.php241-244

Sources: src/CacheManager.php204-300

Plugin Architecture

The cache system uses a plugin architecture where store implementations are interchangeable through the Store contract. This enables:

1. Backend Flexibility: Switch storage backends via configuration without code changes
2. Custom Drivers: Register custom store implementations via extend() src/CacheManager.php142-147
3. Proxy Pattern: Wrap stores with additional behavior (e.g., StackStoreProxy)
4. Optional Features: Implement additional interfaces for advanced capabilities

Core Contracts

Sources: src/Contracts/Store.php src/Contracts/LockProvider.php src/TaggableStore.php

Extended Capabilities

Stores can optionally implement additional interfaces to provide advanced features:

Interface	Purpose	Implementations
LockProvider	Distributed locking	RedisStore, DatabaseStore, FileStore, ArrayStore, NullStore
TaggableStore	Tag-based cache invalidation	RedisStore, NullStore

The Repository checks for these capabilities at runtime:

• supportsTags() src/Repository.php469-472 checks if the store implements tagging via method_exists($this->store, 'tags')

Custom Driver Registration

Applications can register custom store implementations using the extend() method src/CacheManager.php142-147:

The manager stores custom creators in $customCreators src/CacheManager.php35 and checks for them during resolution src/CacheManager.php180-182

Sources: src/CacheManager.php142-147 src/CacheManager.php35 src/CacheManager.php180-182 src/CacheManager.php196-199

Lifecycle and Bootstrapping

The cache system integrates with the Hyperf framework lifecycle through the ConfigProvider src/ConfigProvider.php

Initialization Sequence

Sources: src/ConfigProvider.php src/Listeners/CreateSwooleTable.php10-25

Dependency Bindings

The ConfigProvider registers the following container bindings:

Contract	Implementation	Scope
Factory	CacheManager	Singleton
Store	Default driver repository	Singleton
Repository	Default driver repository	Singleton

These bindings allow dependency injection:

Event Listener Registration

The system registers event listeners during bootstrap:

• CreateSwooleTable src/Listeners/CreateSwooleTable.php10-25 initializes Swoole tables before server start

Sources: src/ConfigProvider.php src/Listeners/CreateSwooleTable.php10-25

Summary

The hypervel/cache architecture is organized into four distinct layers:

1. Client Layer: Entry points for application code, helpers, and console commands
2. Orchestration Layer: CacheManager (factory) and Repository (unified API)
3. Storage Backend Layer: Seven store implementations conforming to the Store contract
4. Infrastructure Layer: Framework services like event dispatching and configuration

The system follows key design patterns:

• Factory Pattern: CacheManager creates and caches store instances
• Repository Pattern: Repository provides a consistent API across all stores
• Plugin Architecture: Stores implement contracts for interchangeable backends
• Decorator Pattern: Repository wraps stores with events and convenience methods

This architecture enables flexibility (swap backends via config), extensibility (custom drivers), observability (comprehensive events), and maintainability (clear separation of concerns).

For detailed information on specific components, see Core Components. For store implementations, see Cache Stores. For advanced features like tagging and locking, see Advanced Features.

Sources: src/CacheManager.php25-335 src/Repository.php37-734 src/Contracts/Factory.php src/Contracts/Store.php src/ConfigProvider.php