Getting Started

This guide provides installation instructions, basic configuration, and simple usage examples to help developers quickly integrate the Hypervel Redis package into their Hyperf applications. The package provides a Laravel-compatible Redis client built on Hyperf's connection pooling infrastructure.

For detailed information about the internal architecture and transformation system, see Architecture Overview. For advanced connection management features, see Connection Management.

---

Installation

Requirements

The package requires the following dependencies:

Dependency	Version	Purpose
PHP	^8.2	Minimum PHP version
hyperf/redis	~3.1.0	Base Hyperf Redis client
hypervel/support	^0.3	Support utilities

Sources: composer.json28-31

Composer Installation

Install the package via Composer:

The package uses Hyperf's auto-discovery mechanism through the ConfigProvider class, which automatically registers the necessary dependencies when the package is installed.

Sources: composer.json1-43 composer.json36-39

---

Configuration

Automatic Registration

The package integrates with Hyperf through the ConfigProvider class, which registers a custom RedisPool implementation that creates RedisConnection instances with Laravel transformation capabilities.

Dependency Mapping

The ConfigProvider maps the Hyperf base pool class to the custom implementation:

Interface/Base Class	Implementation	Purpose
Hyperf\Redis\Pool\RedisPool	Hypervel\Redis\RedisPool	Creates Laravel-compatible connections

Sources: src/ConfigProvider.php1-19 src/ConfigProvider.php14-16

Redis Pool Configuration

Configure Redis connection pools in your Hyperf configuration file (config/autoload/redis.php):

For multi-pool configuration with separate connections for different purposes (cache, session, etc.), see Multi-Pool Configuration.

Sources: Architecture context (standard Hyperf Redis configuration)

---

Basic Usage

Obtaining a Redis Client

There are two ways to obtain a Redis client instance:

1. Dependency Injection

Inject the Redis class into your controllers, services, or commands:

2. Named Connections

Use the connection() method to access different connection pools:

The connection() method returns a RedisProxy instance configured for the specified pool name.

Sources: src/Redis.php136-141 src/Redis.php19

Executing Redis Commands

The Redis client provides a magic __call method that forwards all Redis commands to the underlying connection:

Command Execution Flow

1. Context Check: Checks if a connection exists in the coroutine context src/Redis.php28
2. Connection Acquisition: Gets connection from context or pool src/Redis.php29 src/Redis.php109-123
3. Transformation Enabled: Sets shouldTransform(true) for Laravel compatibility src/Redis.php122
4. Command Execution: Executes the Redis command src/Redis.php38
5. Event Dispatch: Dispatches CommandExecuted event with timing src/Redis.php43-53
6. Connection Management: Releases or stores connection based on command type src/Redis.php55-69

Sources: src/Redis.php26-77

Common Operations

String Operations

Hash Operations

List Operations

The transformation layer automatically adapts these commands to match Laravel's Redis API conventions. For detailed information about specific transformations, see Command Transformations.

Sources: src/Redis.php26-77

---

Connection Context Management

Stateful Operations

Certain Redis operations require multiple commands to execute on the same connection. The Redis client automatically manages connection persistence for these commands:

Commands Requiring Connection Persistence

The following commands automatically store their connection in the coroutine context:

Command	Purpose	Context Key
multi	Begin transaction	redis.connection.{poolName}
pipeline	Begin pipeline	redis.connection.{poolName}
select	Switch database	redis.connection.{poolName}

When these commands execute successfully, the connection is stored in the coroutine context and automatically released at the end of the coroutine via a defer() callback.

Sources: src/Redis.php97-104 src/Redis.php55-69 src/Redis.php127-131

Transaction Example

For detailed information about context management, see Context Management.

Sources: src/Redis.php55-69

---

Quick Start Workflow

Complete Integration Steps

Step-by-Step Guide

1. Install Package: Run composer require hypervel/redis
2. Configure Pools: Create or update config/autoload/redis.php with connection settings
3. Inject Client: Add Redis dependency to your class constructor
4. Execute Commands: Use Laravel-compatible Redis methods
5. Optional: Configure additional named pools for separation of concerns

Sources: composer.json1-43 src/ConfigProvider.php1-19 src/Redis.php14-24

---

Named Connection Pools

Accessing Multiple Pools

Use the connection() method to work with different Redis pools:

Usage Example

The connection() method retrieves a RedisProxy instance from the RedisFactory, which maintains a registry of named pool clients.

For complete multi-pool configuration examples, see Multi-Pool Configuration. For implementation details, see Redis Factory and Redis Proxy.

Sources: src/Redis.php136-141

---

Next Steps

After completing this guide, explore the following topics:

• Architecture Overview: Understand the transformation layer and connection management system
• Redis Client: Learn about advanced client features, context management, and event system
• RedisConnection: Discover how Laravel transformations work under the hood
• Connection Management: Configure multi-pool setups and connection pooling strategies
• Rate Limiting: Use the built-in distributed rate limiter for API throttling

Sources: Architecture diagrams, Table of contents