Installation and Configuration

This page provides instructions for installing the hypervel/cache package and configuring its various cache store backends. It covers Composer installation, framework integration, configuration file structure, and the settings available for each supported cache driver (array, file, redis, swoole, stack, database).

For information about the system architecture and how these components work together, see Architecture Overview. For details on framework-specific integration mechanisms, see Framework Integration.

---

Installation

Composer Package Installation

The package is installed via Composer with the following command:

Sources: composer.json1-53

System Requirements

The package requires the following dependencies:

Dependency	Version	Purpose
PHP	^8.2	Minimum PHP version
hyperf/config	~3.1.0	Configuration management
hyperf/support	~3.1.0	Framework utilities
laravel/serializable-closure	^1.3	Closure serialization
psr/simple-cache	^3.0	PSR-16 cache interface

Sources: composer.json31-36

Optional Dependencies

Additional packages are required for specific cache drivers:

Package	Version	Required For
hyperf/redis	~3.1.0	Redis cache driver
hypervel/cache	~0.1.0	File-based locking

Sources: composer.json38-41

---

Configuration File Publishing

The package integrates with Hyperf through the ConfigProvider class, which registers services, event listeners, console commands, and publishable configuration files.

Publishing the Configuration

To publish the default configuration file, use the Hyperf vendor publish command:

This copies the configuration from the package to your application:

• Source: vendor/hypervel/cache/publish/cache.php
• Destination: config/autoload/cache.php

Sources: src/ConfigProvider.php31-38

Configuration Provider Registration

The ConfigProvider class automatically registers when the package is installed:

Diagram: ConfigProvider Registration Flow

The ConfigProvider registers the following components:

• Dependencies: Binds Factory::class to CacheManager::class and Store::class to the default driver
• Listeners: CreateSwooleTable initializes Swoole tables on server start, CreateTimer sets up interval tasks
• Commands: ClearCommand and PruneDbExpiredCommand for cache management
• Publishable Config: The cache.php configuration file

Sources: src/ConfigProvider.php1-41 composer.json45-48

---

Configuration File Structure

The published configuration file defines the cache system's behavior. It contains four main sections:

Diagram: Configuration File Structure

Sources: publish/cache.php1-111

Default Cache Store

The default key specifies which store to use when no explicit store is requested:

Configuration Key	Environment Variable	Default Value	Description
default	CACHE_DRIVER	'array'	The default cache store name

Sources: publish/cache.php22

Cache Stores Section

The stores array defines all available cache backends. Each store has a driver key that determines its implementation.

Supported drivers: array, file, redis, swoole, stack, database, null

Sources: publish/cache.php37-83

Swoole Tables Configuration

The swoole_tables section defines Swoole shared memory tables used by the swoole driver:

Configuration Key	Default Value	Description
swoole_tables.default.rows	1024	Maximum number of rows
swoole_tables.default.bytes	10240	Memory size per row in bytes
swoole_tables.default.conflict_proportion	0.2	Hash collision buffer ratio

Sources: publish/cache.php91-96

Cache Key Prefix

The prefix setting prevents key collisions when multiple applications share the same cache backend:

Configuration Key	Environment Variable	Default Behavior	Description
prefix	CACHE_PREFIX	APP_NAME slug + _cache	Prefix for all cache keys

The default prefix is generated from the APP_NAME environment variable, converted to a slug format.

Sources: publish/cache.php110

---

Store Configuration

Each cache store driver has specific configuration options. The following sections detail the configuration for each supported driver.

Diagram: Store Driver Configuration Mapping

Sources: publish/cache.php37-83

Array Store Configuration

The array driver stores cache entries in memory for the current process only. It is primarily used for testing and development.

Configuration Key	Type	Default	Description
driver	string	'array'	Driver identifier
serialize	bool	false	Whether to serialize values

Configuration Example:

Sources: publish/cache.php38-41

File Store Configuration

The file driver stores cache entries as files on the filesystem.

Configuration Key	Type	Default	Description
driver	string	'file'	Driver identifier
path	string	BASE_PATH . '/storage/cache/data'	Directory for cache files
lock_path	string	BASE_PATH . '/storage/cache/data'	Directory for lock files

Configuration Example:

Sources: publish/cache.php43-47

Redis Store Configuration

The redis driver uses Redis for distributed caching.

Configuration Key	Type	Default	Description
driver	string	'redis'	Driver identifier
connection	string	'default'	Redis connection name from config/autoload/redis.php
lock_connection	string	'default'	Redis connection for distributed locks

Configuration Example:

The connection value references a connection defined in the Hyperf Redis configuration file.

Sources: publish/cache.php49-53

Swoole Store Configuration

The swoole driver uses Swoole shared memory tables for high-performance caching across workers.

Configuration Key	Type	Default	Description
driver	string	'swoole'	Driver identifier
table	string	'default'	Swoole table name from swoole_tables config
memory_limit_buffer	float	0.05	Memory buffer ratio (5%) before eviction
eviction_policy	int	SwooleStore::EVICTION_POLICY_LRU	Eviction algorithm constant
eviction_proportion	float	0.05	Proportion of entries to evict (5%)
eviction_interval	int	10000	Cleanup interval in milliseconds

Eviction Policy Constants:

• SwooleStore::EVICTION_POLICY_LRU - Least Recently Used
• SwooleStore::EVICTION_POLICY_LFU - Least Frequently Used
• SwooleStore::EVICTION_POLICY_TTL - Time To Live based
• SwooleStore::EVICTION_POLICY_NONE - No automatic eviction

Configuration Example:

For detailed information on eviction policies, see Memory Management and Eviction.

Sources: publish/cache.php55-62

Stack Store Configuration

The stack driver combines multiple cache stores into a multi-tier caching strategy.

Configuration Key	Type	Default	Description
driver	string	'stack'	Driver identifier
stores	array	See example	Array of store configurations with optional TTL overrides

Store Array Structure:

Each element in the stores array can be either:

• A string store name: 'redis'
• An associative array with TTL override: 'swoole' => ['ttl' => 3]

Configuration Example:

This configuration creates a two-tier cache where swoole acts as a fast L1 cache with a 3-second TTL, and redis serves as the L2 persistent cache. For more information, see Stack Store.

Sources: publish/cache.php64-72

Database Store Configuration

The database driver stores cache entries in a SQL database table.

Configuration Key	Type	Environment Variable	Default	Description
driver	string	-	'database'	Driver identifier
connection	string	DB_CACHE_CONNECTION	DB_CONNECTION or 'default'	Database connection name
table	string	DB_CACHE_TABLE	'cache'	Cache entries table name
lock_connection	string|null	DB_CACHE_LOCK_CONNECTION	null	Database connection for locks (null uses connection)
lock_table	string	DB_CACHE_LOCK_TABLE	'cache_locks'	Lock entries table name
lock_lottery	array	-	[2, 100]	Lottery odds for lock cleanup [chances, total]
lock_timeout	int	-	86400	Lock expiration timeout in seconds

Configuration Example:

Lock Lottery: The [2, 100] configuration means there is a 2 in 100 chance that expired locks will be cleaned up on each lock acquisition attempt.

Sources: publish/cache.php74-82

---

Environment Variables

The configuration file supports the following environment variables for runtime configuration:

Environment Variable	Default	Purpose	Used In
CACHE_DRIVER	'array'	Default cache store	Default store selection
CACHE_PREFIX	Generated from APP_NAME	Cache key prefix	Key prefixing
APP_NAME	'hyperf'	Application name	Prefix generation
DB_CACHE_CONNECTION	Falls back to DB_CONNECTION	Database connection	Database store
DB_CONNECTION	'default'	Default DB connection	Database store fallback
DB_CACHE_TABLE	'cache'	Cache table name	Database store
DB_CACHE_LOCK_CONNECTION	null	Lock DB connection	Database locks
DB_CACHE_LOCK_TABLE	'cache_locks'	Lock table name	Database locks

Sources: publish/cache.php22 publish/cache.php76-79 publish/cache.php110

---

Console Commands

The package provides console commands for cache management, which are automatically registered by the ConfigProvider:

Command	Class	Purpose
cache:clear	ClearCommand::class	Clear all cache entries
cache:prune-db-expired	PruneDbExpiredCommand::class	Remove expired entries from database cache

For detailed usage information, see Console Commands.

Sources: src/ConfigProvider.php27-30 src/Console/PruneDbExpiredCommand.php1-66

---

Event Listeners

The package registers event listeners that initialize resources during server startup:

Diagram: Swoole Table Initialization Flow

Listener	Event	Purpose
CreateSwooleTable::class	BeforeServerStart::class	Initializes Swoole tables before server starts
CreateTimer::class	BeforeServerStart::class	Sets up interval timers for cleanup tasks

The CreateSwooleTable listener iterates through all configured stores with driver: 'swoole' and initializes their corresponding Swoole tables via the SwooleTableManager.

Sources: src/ConfigProvider.php23-26 src/Listeners/CreateSwooleTable.php1-25