Overview

This document provides a comprehensive introduction to the hypervel/cache library, covering its purpose, architecture, core components, and key features. For detailed installation and configuration instructions, see Installation and Configuration. For in-depth technical details about specific components, refer to the Core Components and Cache Stores sections.

Purpose and Scope

The hypervel/cache package is a flexible caching library for Hyperf applications that provides a unified interface across multiple storage backends. The library implements PSR-16 SimpleCache and extends it with enterprise features including distributed locking, cache tagging, rate limiting, and sophisticated memory management with eviction policies.

Primary Use Cases:

• Applications requiring multiple cache backends (database, Redis, file, shared memory)
• High-performance scenarios using Swoole shared memory with LRU/LFU/TTL eviction
• Distributed systems needing cache coordination via locks
• Multi-tier caching strategies combining fast local and persistent distributed caches

Sources: composer.json1-12

What is hypervel/cache

hypervel/cache is a PSR-16 compliant caching library that extends beyond simple key-value storage to provide enterprise-grade caching capabilities. The library implements a factory pattern with multiple store drivers, allowing applications to seamlessly switch between different caching backends or use them in combination through stack configurations.

Sources: composer.json1-53

Key Features

The library offers several distinctive features that set it apart from basic caching solutions:

Feature	Description	Key Components
Multi-Driver Support	Seven different cache stores for various use cases	DatabaseStore, RedisStore, SwooleStore, FileStore, ArrayStore, StackStore, NullStore
High-Performance Memory Caching	Swoole-based shared memory with eviction policies	SwooleStore, SwooleTable, LRU/LFU/TTL eviction
Distributed Locking	Multiple locking mechanisms for concurrent access	DatabaseLock, RedisLock, FileLock, CacheLock
Cache Tagging	Group and invalidate related cache entries	TaggedCache, RedisTagSet
Rate Limiting	Built-in rate limiting with cache backend	RateLimiter, Limit classes
Event-Driven Architecture	Comprehensive event system for monitoring	Cache hit/miss/write/flush events
Stack Caching	Multi-layer caching with fallback strategies	StackStore with configurable store chains

Sources: composer.json2-12 architectural diagrams from context

System Architecture

The library follows a three-layer architecture: application interface, cache orchestration, and storage backends.

Architectural Layers

The CacheManager class acts as a factory that resolves driver configurations and creates Repository instances. Each Repository wraps a concrete Store implementation, providing the application-facing cache API with event dispatching and serialization. The architecture enables switching between backends or combining multiple stores via StackStore for tiered caching.

Sources: src/CacheManager.php1-335 src/Repository.php1-800 composer.json27-29

Key Components and Code Mapping

Component Mapping Table

System Concept	Code Entity	Location	Role
Factory	CacheManager	src/CacheManager.php25-335	Creates and caches store instances
Unified API	Repository	src/Repository.php1-800	Wraps stores with events and serialization
Store Contract	Store interface	src/Contracts/Store.php1-50	Defines cache operations
Lock Contract	LockProvider interface	src/Contracts/LockProvider.php1-20	Defines locking operations
Bootstrap	ConfigProvider	src/ConfigProvider.php1-150	Hyperf integration point
Helper	cache() function	src/Functions.php1-30	Global access function
Event Listener	CreateSwooleTable	src/Listeners/CreateSwooleTable.php10-25	Initializes Swoole tables on server start

Store Implementation Mapping

Sources: src/Contracts/Store.php1-50 src/Contracts/LockProvider.php1-20 src/SwooleStore.php1-500 src/RedisStore.php1-400

Installation and Requirements

System Requirements

The library requires modern PHP and specific framework components:

• PHP Version: ^8.2
• Core Dependencies:
  • hyperf/config ~3.1.0
  • hyperf/support ~3.1.0
  • laravel/serializable-closure ^1.3
  • psr/simple-cache ^3.0

Optional Dependencies

For full functionality, these packages are recommended:

• hyperf/redis ~3.1.0 - Required for Redis-based stores and tagging
• hypervel/cache ~0.1.0 - Required for file locking mechanisms

Sources: composer.json31-41

Framework Integration

The library integrates with Hyperf through the ConfigProvider class, which is automatically discovered via the composer.json extra configuration:

The ConfigProvider registers:

• Dependency injection bindings for CacheManager and store interfaces
• Event listeners (CreateSwooleTable for Swoole table initialization)
• Console commands (cache:clear, cache:prune-db-expired, cache:prune-expired)
• Configuration file publishing

PSR-4 autoloading maps the Hypervel\Cache namespace to the src/ directory, and global helper functions are loaded via:

This provides the global cache() helper function for convenient cache access throughout the application.

Sources: composer.json46-52 composer.json23-30 src/ConfigProvider.php1-150

License and Support

hypervel/cache is released under the MIT License, providing maximum flexibility for both commercial and open-source usage. The license covers contributions from Taylor Otwell (Laravel), Hyperf, and Hypervel teams.

Support Channels:

• Issues: https://github.com/hypervel/components/issues
• Source Code: https://github.com/hypervel/components
• Documentation Badge: DeepWiki integration available

Sources: LICENSE.md1-25 composer.json19-22 README.md1-4

Extended SwooleTable Implementation

One of the key differentiators is the enhanced SwooleTable class that extends Swoole's native table with additional validation and safety features:

This implementation adds column size validation to prevent data truncation errors and provides better error messaging when values exceed configured column sizes.

Sources: src/SwooleTable.php13-64