Cache Stores

Purpose and Scope

This document provides an overview of all available cache store implementations in the hypervel/cache package. It explains the characteristics of each store type (performance, persistence, distribution capabilities), their configuration options, and guidance on selecting the appropriate store for specific use cases.

For detailed information about specific store implementations, see the child sections: Database Store, Swoole Store, Stack Store, Redis Store, File Store, and Array and Null Stores. For information on how stores are created and managed, see Cache Manager. For the contract that all stores implement, see Store Contracts.

---

Store Architecture

Cache stores are the concrete implementations that handle the actual storage and retrieval of cached data. All stores implement the Store interface defined in src/Contracts/Store.php ensuring a consistent API across different storage backends.

The CacheManager class acts as a factory for creating store instances using the factory pattern. Each store is configured via the cache.stores array in publish/cache.php and instantiated through dedicated factory methods in src/CacheManager.php202-300

Store Creation Flow

Store Creation Flow

Sources: src/CacheManager.php172-300

---

Available Store Implementations

The package provides seven store implementations, each optimized for different use cases:

Store	Driver Name	Class	Persistence	Distribution	Performance	Tagging	Locking
Array	array	ArrayStore	Volatile	Process-local	Fastest	No	Yes
File	file	FileStore	Persistent	Local	Medium	No	Yes
Redis	redis	RedisStore	Persistent	Distributed	Fast	Yes	Yes
Swoole	swoole	SwooleStore	Volatile	Server-wide	Very Fast	No	No
Database	database	DatabaseStore	Persistent	Distributed	Slow	No	Yes
Stack	stack	StackStore	Composite	Composite	Variable	No	No
Null	null	NullStore	None	N/A	Instant	Yes	Yes

---

Store Characteristics Mapping

Store Classification by Persistence and Driver Names

Sources: src/CacheManager.php184-300 publish/cache.php37-83

---

Store Factory Methods and Configuration Keys

The CacheManager resolves store configurations and instantiates stores using dedicated factory methods. The driver name in configuration determines which factory method is invoked.

Factory Method Resolution from Configuration to Store Instance

Sources: src/CacheManager.php172-191 src/CacheManager.php202-300

---

Configuration Structure

Each store is configured in the cache.stores array using its driver name as the key. The configuration structure varies by driver type:

Array Store Configuration

Configuration keys: driver, serialize
Factory method: src/CacheManager.php204-207
Store class: ArrayStore

File Store Configuration

Configuration keys: driver, path, lock_path, permission
Factory method: src/CacheManager.php212-220
Store class: FileStore

Redis Store Configuration

Configuration keys: driver, connection, lock_connection
Factory method: src/CacheManager.php233-245
Store class: RedisStore

Swoole Store Configuration

Configuration keys: driver, table, memory_limit_buffer, eviction_policy, eviction_proportion, eviction_interval
Factory method: src/CacheManager.php250-261
Store class: SwooleStore

Database Store Configuration

Configuration keys: driver, connection, table, lock_connection, lock_table, lock_lottery, lock_timeout
Factory method: src/CacheManager.php285-300
Store class: DatabaseStore

Stack Store Configuration

Configuration keys: driver, stores (array of store names with optional TTL overrides)
Factory method: src/CacheManager.php266-280
Store class: StackStore

Null Store Configuration

The null store requires no configuration and can be instantiated with just the driver name:

Factory method: src/CacheManager.php225-228
Store class: NullStore

Sources: publish/cache.php37-83 src/CacheManager.php202-300

---

Store Selection Guide

Choosing the appropriate cache store depends on several factors:

Selection Decision Tree

Store Selection Decision Tree

Performance Characteristics

Store	Read Latency	Write Latency	Throughput	Memory Efficiency
ArrayStore	~1µs	~1µs	Very High	Low (process-local)
SwooleStore	~5µs	~5µs	Very High	High (shared memory)
RedisStore	~100µs	~100µs	High	Medium (network)
FileStore	~500µs	~1ms	Medium	High (disk)
DatabaseStore	~1ms	~2ms	Low	High (disk)
StackStore	Variable	Variable	Variable	Composite
NullStore	0	0	Infinite	Zero

Note: Latency values are approximate and depend on hardware, network, and workload.

Use Case Recommendations

Use Case	Recommended Store	Alternative
HTTP session data (distributed)	RedisStore	DatabaseStore
API rate limiting	RedisStore	SwooleStore
Configuration cache	FileStore	ArrayStore
Query result cache	StackStore (Swoole + Redis)	RedisStore
Rendered view fragments	FileStore	RedisStore
Real-time analytics	SwooleStore	ArrayStore
Testing/development	ArrayStore or NullStore	-
Multi-region deployment	RedisStore with replication	DatabaseStore
Tagged cache invalidation	RedisStore	-
Distributed job locks	RedisStore or DatabaseStore	-

Sources: src/CacheManager.php202-300 publish/cache.php37-83

---

Store Interface Implementation

All stores implement the Store interface, which defines the core cache operations:

Store Interface and Implementations

Additional capabilities are provided through optional interfaces:

• LockProvider: Implemented by stores supporting distributed locking (ArrayStore, FileStore, RedisStore, DatabaseStore, NullStore)
• TaggableStore: Extended by stores supporting tagged caching (RedisStore, NullStore)

For details on these contracts, see Store Contracts.

Sources: src/Contracts/Store.php src/CacheManager.php202-300

---

Custom Store Registration

The CacheManager supports custom store implementations through the extend() method. Custom stores can be registered in service providers:

After registration, configure the custom store in publish/cache.php:

Custom stores must implement the Store interface defined in src/Contracts/Store.php

Sources: src/CacheManager.php142-147

---

Default Store Configuration

The default cache store is configured via the cache.default key in publish/cache.php22:

This determines which store is used when no specific store name is provided:

The default driver can be changed at runtime using setDefaultDriver():

Sources: publish/cache.php22 src/CacheManager.php98-111