Core Components

This document introduces the three fundamental building blocks of the hypervel/cache system: CacheManager, Repository, and Store contracts. These components work together to provide a flexible, driver-agnostic caching layer using the Factory and Facade design patterns.

For detailed information about specific store implementations, see Cache Stores. For framework integration and initialization, see Framework Integration.

---

Component Overview

The caching system is built on three core abstractions that work together in a layered architecture:

Component	Pattern	Role	Location
CacheManager	Factory	Creates and manages cache store instances	src/CacheManager.php
Repository	Facade	Provides unified API for cache operations	src/Repository.php
Store	Contract	Defines storage backend interface	src/Contracts/Store.php

The CacheManager acts as a factory that reads configuration and instantiates appropriate Store implementations, then wraps them in a Repository facade. Applications interact exclusively with the Repository, which delegates operations to the underlying Store while providing additional features like event dispatching, TTL normalization, and the remember pattern.

Sources: src/CacheManager.php25-335 src/Repository.php36-631 src/Contracts/Store.php7-59

---

Component Architecture

Diagram: Three-Layer Architecture

This diagram shows how the three core components form a three-layer architecture. The CacheManager factory creates Repository instances that wrap Store implementations. All stores implement the Store interface, ensuring polymorphism and allowing the Repository to work with any storage backend without knowing implementation details.

Sources: src/CacheManager.php25-335 src/Repository.php36-631 src/Contracts/Store.php7-59

---

CacheManager: Factory Pattern

The CacheManager class implements the Factory pattern to instantiate cache stores based on configuration. It serves as the entry point for obtaining cache instances.

Key Responsibilities

Responsibility	Methods	Description
Driver Resolution	store(), driver(), resolve()	Reads configuration and creates appropriate store instances
Store Caching	stores property	Maintains singleton instances of resolved stores
Custom Drivers	extend(), customCreators	Allows registration of custom driver creators
Event Integration	setEventDispatcher()	Optionally enables event dispatching on repositories

Core Methods

Diagram: CacheManager Method Flow

The store() method is the primary entry point src/CacheManager.php56-61 It resolves the driver name, checks the cached stores array, and calls resolve() if needed src/CacheManager.php172-191 The resolve() method reads configuration, calls the appropriate create{Driver}Driver() method src/CacheManager.php184-188 and returns a Repository wrapping the store.

Driver Creation Methods

The CacheManager contains factory methods for each built-in driver:

• createArrayDriver() src/CacheManager.php204-207 - Creates in-memory ArrayStore
• createFileDriver() src/CacheManager.php212-220 - Creates filesystem-based FileStore
• createRedisDriver() src/CacheManager.php233-245 - Creates Redis-backed RedisStore
• createSwooleDriver() src/CacheManager.php250-261 - Creates Swoole table-backed SwooleStore
• createDatabaseDriver() src/CacheManager.php285-300 - Creates database-backed DatabaseStore
• createStackDriver() src/CacheManager.php266-280 - Creates multi-tier StackStore
• createNullDriver() src/CacheManager.php225-228 - Creates no-op NullStore

Each method instantiates the specific store class with configuration parameters and passes it to repository() src/CacheManager.php74-81 which wraps it in a Repository instance.

Custom Driver Registration

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

The closure is stored in customCreators and invoked via callCustomCreator() src/CacheManager.php196-199 when the driver is resolved.

Sources: src/CacheManager.php25-335

---

Repository: Facade Pattern

The Repository class implements the Facade pattern, providing a unified, high-level API for cache operations while delegating to the underlying Store implementation.

Key Responsibilities

Responsibility	Methods	Description
Cache Operations	get(), put(), forget(), flush()	Standard cache CRUD operations
TTL Normalization	getSeconds()	Converts various TTL formats to seconds
Event Dispatching	event()	Fires lifecycle events for observability
Convenience Patterns	remember(), sear(), pull()	Higher-level caching patterns
Array Access	offsetGet(), offsetSet()	Implements ArrayAccess interface

Operation Flow

Diagram: Repository Operation Sequence

This diagram shows the flow for get() src/Repository.php117-139 and put() src/Repository.php190-216 operations. The Repository fires events before and after delegating to the Store, enabling observability without coupling the store implementations to the event system.

Key Methods

Read Operations

• get(key, default) src/Repository.php117-139 - Retrieves a value, returning default on miss
• many(keys) src/Repository.php145-158 - Retrieves multiple values by keys
• has(key) src/Repository.php95-98 - Checks if key exists (via get())
• pull(key, default) src/Repository.php180-185 - Gets and deletes atomically

Write Operations

• put(key, value, ttl) src/Repository.php190-216 - Stores a value with TTL
• putMany(values, ttl) src/Repository.php229-254 - Stores multiple values
• forever(key, value) src/Repository.php316-329 - Stores without expiration
• add(key, value, ttl) src/Repository.php264-295 - Stores only if key doesn't exist

Delete Operations

• forget(key) src/Repository.php398-409 - Removes a key
• flush() (via clear()) src/Repository.php429-442 - Removes all keys

TTL Handling

The Repository normalizes TTL values into seconds using getSeconds() src/Repository.php613-622:

• Integer: Treated as seconds
• DateTimeInterface: Calculates seconds until that time
• DateInterval: Converts interval to seconds
• null: Uses default TTL or stores forever

This normalization allows the Store implementations to work exclusively with integer seconds, simplifying their implementation.

Remember Pattern

The remember() method src/Repository.php340-354 implements a common caching pattern:

1. Attempts to retrieve the value from cache
2. If found, returns it immediately
3. If not found, executes the callback
4. Stores the callback result with the specified TTL
5. Returns the result

This pattern reduces boilerplate for cache-aside logic. The sear() src/Repository.php365-368 and rememberForever() src/Repository.php379-393 methods provide variants that store values indefinitely.

Magic Method Delegation

The Repository implements __call() src/Repository.php75-82 to delegate unknown methods to the underlying Store. This allows store-specific methods to be called directly on the repository, such as lock operations or increment/decrement.

Sources: src/Repository.php36-631

---

Store Contract

The Store interface src/Contracts/Store.php7-59 defines the contract that all cache storage backends must implement. This contract ensures polymorphism and allows the Repository to work with any storage backend.

Interface Definition

Diagram: Store Interface and Implementations

All cache stores implement the Store interface, ensuring they provide the same basic operations. This polymorphism allows the Repository to work with any store type without knowing implementation details.

Required Methods

Method	Parameters	Return	Purpose
get	string $key	mixed	Retrieve a value by key
many	array $keys	array	Retrieve multiple values
put	string $key, mixed $value, int $seconds	bool	Store a value with TTL
putMany	array $values, int $seconds	bool	Store multiple values
increment	string $key, int $value = 1	bool|int	Increment numeric value
decrement	string $key, int $value = 1	bool|int	Decrement numeric value
forever	string $key, mixed $value	bool	Store without expiration
forget	string $key	bool	Remove a key
flush	-	bool	Remove all keys
getPrefix	-	string	Get key prefix

Method Contracts

Retrieval Methods

• get(key) src/Contracts/Store.php12 - Returns the value or null if not found or expired
• many(keys) src/Contracts/Store.php18 - Returns an associative array with null for missing keys

Storage Methods

• put(key, value, seconds) src/Contracts/Store.php23 - Returns true on success, false on failure. The seconds parameter is always a positive integer.
• putMany(values, seconds) src/Contracts/Store.php28 - Stores multiple key-value pairs with the same TTL
• forever(key, value) src/Contracts/Store.php43 - Stores without expiration (must persist indefinitely)

Atomic Operations

• increment(key, value) src/Contracts/Store.php33 - Returns new value on success, false on failure
• decrement(key, value) src/Contracts/Store.php38 - Returns new value on success, false on failure

These methods must be atomic to prevent race conditions in concurrent environments.

Deletion Methods

• forget(key) src/Contracts/Store.php48 - Returns true if key was deleted, false if key didn't exist
• flush() src/Contracts/Store.php53 - Removes all keys from the store

Example Implementation: StackStore

The StackStore src/StackStore.php11-184 demonstrates how a store implements the contract:

Diagram: StackStore Implementation Pattern

The StackStore implements the Store interface by orchestrating multiple underlying stores. Its get() method src/StackStore.php20-25 delegates to getOrRestoreRecord() src/StackStore.php107-127 which checks stores in sequence. Its put() method src/StackStore.php32-40 wraps the value in a record and calls putRecord() src/StackStore.php129-135 which writes to all stores.

Sources: src/Contracts/Store.php7-59 src/StackStore.php11-184

---

Component Interaction

Diagram: End-to-End Component Interaction

This sequence shows how the three core components collaborate from initialization through runtime operations:

1. Initialization: Application requests a cache store from CacheManager src/CacheManager.php56-61
2. Configuration: CacheManager reads configuration via ConfigInterface
3. Store Creation: CacheManager instantiates the appropriate Store implementation src/CacheManager.php172-191
4. Repository Wrapping: Store is wrapped in a Repository src/CacheManager.php74-81
5. Caching: Resolved repository is cached in CacheManager.stores src/CacheManager.php60
6. Operations: Application uses Repository methods which delegate to Store src/Repository.php340-354

Separation of Concerns

Component	Concerns	Does NOT Handle
CacheManager	Configuration, instantiation, singleton caching	Cache operations, TTL conversion, events
Repository	API uniformity, TTL normalization, events, patterns	Storage logic, driver-specific features
Store	Storage operations, expiration, atomicity	TTL format parsing, event dispatching

This separation allows each component to evolve independently. For example, new event types can be added to Repository without modifying stores, and new store implementations need only satisfy the Store contract without understanding TTL formats or events.

Sources: src/CacheManager.php25-335 src/Repository.php36-631 src/Contracts/Store.php7-59

---

StackStoreProxy: Decorator Pattern

While not a core component itself, StackStoreProxy src/StackStoreProxy.php10-82 demonstrates how stores can be composed and extended. It implements the Decorator pattern to wrap a Store and modify its behavior.

Purpose

The StackStoreProxy enforces maximum TTL limits on individual stores within a StackStore. This allows multi-tier caches to have different expiration policies per tier.

Implementation

Diagram: StackStoreProxy Decorator Pattern

The proxy intercepts put() calls src/StackStoreProxy.php26-33 and enforces a maximum TTL if configured. Other methods are passed through to the wrapped store src/StackStoreProxy.php74-81 This allows the StackStore to compose different stores with different TTL policies without modifying the store implementations themselves.

For example, a fast L1 cache (Swoole) might be limited to 3-second TTL, while L2 (Redis) allows longer durations:

Sources: src/StackStoreProxy.php10-82 src/CacheManager.php266-280

---

Related Documentation

• For detailed information on each store implementation, see Cache Stores
• For locking capabilities provided by stores, see Distributed Locking
• For event dispatching and observability, see Event System
• For framework bootstrap and dependency injection, see Framework Integration