Overview

What is hypervel/redis?

hypervel/redis is a Laravel-compatible Redis client for Hyperf applications. It provides a transformation layer that adapts Hyperf's Redis implementation to match Laravel's API conventions, enabling developers to use familiar Laravel Redis patterns in Hyperf's coroutine environment.

Key Value Proposition: Bridge between Laravel's Redis API and Hyperf's high-performance coroutine architecture without requiring code changes.

The package consists of three primary layers:

Layer	Key Classes	Purpose
Client Layer	Redis, RedisProxy	Command execution facade with connection lifecycle management
Transformation Layer	RedisConnection	Laravel API compatibility through method interception and result transformation
Infrastructure Layer	RedisPool, RedisFactory, ConfigProvider	Connection pooling, instance creation, and Hyperf framework integration

Sources: composer.json1-44 README.md1-5

Core Components

The package's architecture centers around two critical components, shown with their relative importance to the system:

Component Importance:

Component	File	Importance	Role
RedisConnection	src/RedisConnection.php	12.20	Most critical: transforms Hyperf Redis to Laravel API
Redis	src/Redis.php	12.05	Primary facade: connection management and command execution
RedisProxy	src/RedisProxy.php	2.68	Pool-specific client instances
RedisFactory	src/RedisFactory.php	0.68	Named pool management
RedisPool	src/RedisPool.php	0.68	Connection pool lifecycle
ConfigProvider	src/ConfigProvider.php	0.68	Hyperf framework integration
DurationLimiter	src/Limit/DurationLimiter.php	0.68	Redis-backed rate limiting

Sources: composer.json23-26

Package Metadata

Property	Value
Package Name	hypervel/redis
Namespace	Hypervel\Redis\
PHP Version	^8.2
License	MIT
Primary Dependencies	hyperf/redis ~3.1.0 hypervel/support ^0.3
Repository	https://github.com/hypervel/components

Sources: composer.json2-32

Key Features

Laravel API Compatibility

The package provides Laravel-style command transformations, converting Redis responses to match Laravel's conventions:

• false return values from get() are transformed to null
• hmget() returns associative arrays with null for missing keys
• zadd() accepts arrays with score => member format
• Scan operations return arrays instead of cursor + results tuples

For details on transformations, see Transformation System and Command Transformations.

Coroutine Context Management

Stateful Redis operations (multi, pipeline, select) maintain connection state across coroutines using context storage:

• Connections are stored in coroutine-local context keyed by pool name
• Commands like multi() automatically bind subsequent commands to the same connection
• Context is cleared when transactions complete or connections are released

For implementation details, see Context Management.

Connection Pooling

Multiple named connection pools enable efficient resource management:

• Each pool maintains a configurable number of persistent connections
• Pools are created per configuration (default, cache, session, etc.)
• Connections are borrowed from pools and automatically released after use
• Stateful operations hold connections in context until completion

For pooling implementation, see Connection Pooling.

Event Monitoring

All Redis commands dispatch CommandExecuted events for observability:

• Events include command name, parameters, execution time, and connection info
• Integrates with Hyperf's event dispatcher
• Enables logging, metrics collection, and debugging

For event system details, see Event System.

Rate Limiting

Built-in Redis-backed rate limiter with sliding window algorithm:

• Atomic operations via Lua scripts
• Configurable rate limits and time windows
• Supports blocking and non-blocking acquisition modes

For rate limiting implementation, see Rate Limiting.

Sources: composer.json1-44

Class Hierarchy and Relationships

The following diagram shows how classes extend and interact with each other:

Inheritance Chain:

Hypervel Class	Extends	Purpose
Redis	Hyperf\Redis\Redis	Adds context management, event dispatching, connection lifecycle
RedisProxy	Hypervel\Redis\Redis	Binds to specific named pool
RedisConnection	Hyperf\Redis\RedisConnection	Adds Laravel API transformations via __call() magic method
RedisPool	Hyperf\Redis\Pool\RedisPool	Returns custom RedisConnection instances

Sources: composer.json23-26

Package Structure

The package follows a simple directory structure:

hypervel/redis/
├── src/
│ ├── Redis.php # Main facade class
│ ├── RedisProxy.php # Pool-specific proxy
│ ├── RedisConnection.php # Connection with transformations
│ ├── RedisPool.php # Connection pool manager
│ ├── RedisFactory.php # Proxy factory
│ ├── ConfigProvider.php # Hyperf integration
│ └── Limit/
│ ├── DurationLimiter.php # Rate limiter implementation
│ └── LimiterTimeoutException.php
├── composer.json # Package metadata
└── README.md

All source files are autoloaded via PSR-4 under the Hypervel\Redis\ namespace.

Sources: composer.json23-26

Hyperf Framework Integration

The package integrates with Hyperf through ConfigProvider, registered in composer.json at composer.json36-39:

Integration Flow:

ConfigProvider Responsibilities:

Method	Purpose
dependencies()	Maps Hyperf\Redis\Pool\RedisPool to custom Hypervel\Redis\RedisPool
__invoke()	Returns combined configuration for framework registration

This mapping ensures that when Hyperf creates Redis pool connections, it uses the custom RedisPool class that creates RedisConnection instances with Laravel transformations.

Sources: composer.json36-39

Core Concepts

Named Connection Pools

The package supports multiple independent connection pools, each identified by a string name (e.g., default, cache, session). Each pool:

• Has its own configuration (host, port, database, connection limits)
• Maintains a separate set of Redis connections
• Can be accessed through pool-specific RedisProxy instances

For multi-pool configuration, see Multi-Pool Configuration.

Transformation Mode

RedisConnection instances can operate in two modes:

• Transformation Enabled (shouldTransform = true): Responses are converted to Laravel-compatible formats
• Transformation Disabled (shouldTransform = false): Raw Redis responses are returned

The transformation mode is typically enabled by default but can be toggled programmatically.

For transformation details, see Transformation System.

Stateful vs Stateless Commands

Commands are categorized based on connection state requirements:

Category	Commands	Behavior
Stateful	multi, pipeline, select	Connection stored in coroutine context for reuse
Stateless	get, set, hget, etc.	Connection borrowed and immediately released

This distinction enables efficient connection reuse while maintaining correctness for transactional operations.

For context management implementation, see Context Management.

Event-Driven Observability

Every Redis command execution triggers a CommandExecuted event containing:

• Command name and parameters
• Execution time (microseconds)
• Connection pool name
• Connection identifier

Applications can subscribe to these events for logging, metrics, or debugging purposes.

For event system details, see Event System.

Sources: composer.json1-44

Summary

hypervel/redis provides a production-ready Redis client for Hyperf applications with:

• API Compatibility: Laravel-style command transformations
• Efficient Pooling: Connection pool management with automatic lifecycle handling
• Context Awareness: Coroutine-local storage for stateful operations
• Observability: Event-driven command monitoring
• Rate Limiting: Built-in sliding window rate limiter

The package is designed for high-concurrency scenarios leveraging Swoole's coroutine architecture while maintaining familiar APIs for developers transitioning from Laravel.

For next steps:

• Getting Started - Installation and basic usage
• Architecture Overview - Detailed system design
• Redis Facade - Primary API documentation
• Configuration - Setup and pool configuration

Sources: composer.json1-44 README.md1-5