#  php-redis

**Repository Path**: xianrenqh/php-redis

## Basic Information

- **Project Name**:  php-redis
- **Description**: php封装的 redis 扩展应用类
- **Primary Language**: PHP
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-10
- **Last Updated**: 2025-11-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Redis 工具类使用手册

## 概述

本工具类基于 PHP 原生 Redis 扩展封装，提供了字符串、哈希表、列表、集合（有序 / 无序）等 Redis
核心数据结构的操作方法，同时支持配置灵活初始化、事务、数据库管理等功能，简化 Redis 操作流程。

## 一、环境准备

1. 安装 PHP Redis 扩展（推荐版本 ≥ 3.0）
2. 确保 Redis 服务已启动并可正常连接

## 二、初始化与配置

### 2.1 基础初始化

```php
<?php
// 引入类文件
require_once 'libs/Redis.php';
use libs\Redis;

// 方式1：通过构造函数初始化（推荐）
$redis = new Redis([
    'host'     => '127.0.0.1',  // Redis 主机
    'port'     => 6379,         // 端口
    'password' => '',           // 密码（无则留空）
    'db'       => 0,            // 选择数据库
    'expire'   => 3600,         // 默认过期时间（秒）
    'timeout'  => 10            // 连接超时时间（秒）
]);

// 方式2：通过静态方法初始化（构造函数失效时使用）
Redis::_initialize([
    'host' => '192.168.1.100',
    'port' => 6380,
    'db'   => 1
]);
```

### 2.2 切换数据库

```php
// 切换到数据库 2
Redis::selectdb(2);
```

### 2.3 数据库备份与恢复

```php
// 创建当前数据库备份（生成 dump.rdb 文件）
$isSuccess = Redis::savedb();
var_dump($isSuccess); // 成功返回 true

// 恢复：将 dump.rdb 移动到 Redis 安装目录，重启 Redis 服务即可
```

## 三、字符串操作

### 3.1 设置键值（set）

存储字符串、数字、数组、对象等类型，支持自定义过期时间

```php
// 存储数字（自动不序列化，支持自增自减）
Redis::set('user:id', 1001);

// 存储字符串
Redis::set('user:name', '张三');

// 存储数组（自动序列化）
Redis::set('user:info', ['age' => 25, 'gender' => '男']);

// 存储并设置过期时间（300秒）
Redis::set('verify:code', '6789', 300);
```

### 3.2 获取键值（get）

自动反序列化数组 / 对象，数字保持原类型

```php
// 获取数字
$userId = Redis::get('user:id');
var_dump($userId); // int(1001)

// 获取字符串
$userName = Redis::get('user:name');
var_dump($userName); // string(6) "张三"

// 获取数组
$userInfo = Redis::get('user:info');
var_dump($userInfo); // array(2) { ["age"]=>int(25) ["gender"]=>string(3) "男" }
```

### 3.3 设置过期时间（expire）

```php
// 给已存在的键设置过期时间（180秒）
Redis::expire('user:name', 180);
```

### 3.4 删除键值（del）

```php
// 删除单个键
$delCount = Redis::del('verify:code');
var_dump($delCount); // 成功返回 1，不存在返回 0
```

### 3.5 截取字符串（substr）

支持汉字截取

```php
// 存储字符串
Redis::set('article:title', 'Redis 工具类使用手册');

// 从第0位开始截取，取5个字符
$subStr = Redis::substr('article:title', 0, 5);
var_dump($subStr); // string(15) "Redis 工具类"
```

### 3.6 替换键值并返回旧值（replace）

```php
// 先设置初始值
Redis::set('goods:stock', 100);

// 替换并获取旧值
$oldStock = Redis::replace('goods:stock', 95);
var_dump($oldStock); // int(100)
var_dump(Redis::get('goods:stock')); // int(95)
```

### 3.7 批量设置（mset）

```php
// 批量存储键值对
$arr = [
    'site:name' => '我的网站',
    'site:url'  => 'https://example.com',
    'site:pv'   => 0
];
Redis::mset($arr);
```

### 3.8 批量获取（mget）

```php
// 批量获取多个键的值
$values = Redis::mget('site:name', 'site:url', 'site:pv');
var_dump($values); 
// array(3) { 
//   [0]=>string(8) "我的网站" 
//   [1]=>string(21) "https://example.com" 
//   [2]=>int(0) 
// }
```

### 3.9 获取剩余过期时间（expiretime）

```php
// 获取键的剩余过期时间（秒），已过期返回负数
$remainTime = Redis::expiretime('user:name');
var_dump($remainTime); // int(125)（剩余125秒）
```

### 3.10 不存在时设置（setnx）

```php
// 键不存在时设置（成功返回 true）
$isSuccess = Redis::setnx('lock:order', 1);
var_dump($isSuccess); // bool(true)

// 再次设置（失败返回 false）
$isSuccess2 = Redis::setnx('lock:order', 1);
var_dump($isSuccess2); // bool(false)
```

### 3.11 获取值长度（valuelen）

```php
// 字符串长度
$strLen = Redis::valuelen('user:name');
var_dump($strLen); // int(6)（"张三"占6字节）

// 数组长度
$arrLen = Redis::valuelen('user:info');
var_dump($arrLen); // int(2)（数组有2个元素）
```

### 3.12 数字自增（inc）

```php
// 自增1（键不存在时默认从0开始）
$newPv = Redis::inc('site:pv');
var_dump($newPv); // int(1)

// 自增5
$newStock = Redis::inc('goods:stock', 5);
var_dump($newStock); // int(100)
```

### 3.13 数字自减（dec）

```php
// 自减1
$newStock = Redis::dec('goods:stock');
var_dump($newStock); // int(99)

// 自减3
$newStock2 = Redis::dec('goods:stock', 3);
var_dump($newStock2); // int(96)
```

### 3.14 追加值（append）

支持字符串首尾追加、数组元素追加

```php
// 字符串尾部追加
Redis::set('greeting', 'Hello');
Redis::append('greeting', ' World');
var_dump(Redis::get('greeting')); // string(11) "Hello World"

// 字符串头部追加
Redis::append('greeting', 'Hi, ', true);
var_dump(Redis::get('greeting')); // string(15) "Hi, Hello World"

// 数组追加元素（尾部）
Redis::set('tag:list', ['php', 'redis']);
Redis::append('tag:list', 'mysql');
var_dump(Redis::get('tag:list')); // array(3) { [0]=>string(3) "php" [1]=>string(5) "redis" [2]=>string(5) "mysql" }

// 数组头部追加元素
Redis::append('tag:list', 'linux', true);
var_dump(Redis::get('tag:list')); // array(4) { [0]=>string(5) "linux" [1]=>string(3) "php" [2]=>string(5) "redis" [3]=>string(5) "mysql" }
```

## 四、哈希表操作

### 4.1 设置哈希字段（hset）

支持字符串、数组（自动转 JSON）

```php
// 设置单个字段
Redis::hset('user:1001', 'name', '李四');
Redis::hset('user:1001', 'age', 30);

// 设置数组字段（自动转JSON）
Redis::hset('user:1001', 'address', ['province' => '广东', 'city' => '深圳']);

// 设置并设置过期时间（7200秒）
Redis::hset('user:1001', 'status', 1, 7200);
```

### 4.2 获取哈希字段（hget）

```php
// 获取单个字段
$userName = Redis::hget('user:1001', 'name');
var_dump($userName); // string(6) "李四"

// 获取数组字段（需手动转JSON为数组）
$address = Redis::hget('user:1001', 'address');
$addressArr = json_decode($address, true);
var_dump($addressArr); // array(2) { ["province"]=>string(6) "广东" ["city"]=>string(6) "深圳" }
```

### 4.3 删除哈希字段（hdel）

```php
// 删除单个字段
$delCount = Redis::hdel('user:1001', 'status');
var_dump($delCount); // int(1)

// 删除多个字段
$delCount2 = Redis::hdel('user:1001', 'age', 'address');
var_dump($delCount2); // int(2)
```

### 4.4 判断字段是否存在（hexists）

```php
$exists = Redis::hexists('user:1001', 'name');
var_dump($exists); // bool(true)

$exists2 = Redis::hexists('user:1001', 'age');
var_dump($exists2); // bool(false)
```

### 4.5 获取所有字段和值（hgetall）

```php
$userData = Redis::hgetall('user:1001');
var_dump($userData);
// array(1) { 
//   ["name"]=>string(6) "李四" 
// }
```

### 4.6 字段值自增（hinc）

支持整数和浮点数

```php
// 初始化字段值
Redis::hset('goods:101', 'price', 99.9);

// 自增 10.1
$newPrice = Redis::hinc('goods:101', 'price', 10.1);
var_dump($newPrice); // float(110)
```

### 4.7 获取所有字段名（hkeys）

```php
$fields = Redis::hkeys('goods:101');
var_dump($fields); // array(1) { [0]=>string(5) "price" }
```

### 4.8 获取所有字段值（hvals）

```php
$values = Redis::hvals('goods:101');
var_dump($values); // array(1) { [0]=>string(6) "110.0" }
```

### 4.9 获取字段数量（hlen）

```php
$fieldCount = Redis::hlen('user:1001');
var_dump($fieldCount); // int(1)
```

### 4.10 批量获取字段值（hmget）

```php
// 先批量设置字段
Redis::hmset('goods:102', [
    'name'  => 'Redis 实战',
    'price' => 59.8,
    'stock' => 200
]);

// 批量获取字段值
$goodsInfo = Redis::hmget('goods:102', 'name', 'price', 'stock');
var_dump($goodsInfo);
// array(3) { 
//   ["name"]=>string(12) "Redis 实战" 
//   ["price"]=>string(4) "59.8" 
//   ["stock"]=>string(3) "200" 
// }
```

### 4.11 批量设置字段（hmset）

```php
$goodsData = [
    'author' => '张三',
    'press'  => '技术出版社',
    'date'   => '2024-01-01'
];
// 批量设置字段
Redis::hmset('goods:102', $goodsData);

// 批量设置并设置过期时间（3600秒）
Redis::hmset('goods:102', ['sales' => 0], 3600);
```

### 4.12 不存在时设置字段（hsetnx）

```php
// 字段不存在时设置
$isSuccess = Redis::hsetnx('goods:102', 'discount', 0.9);
var_dump($isSuccess); // bool(true)

// 字段已存在，设置失败
$isSuccess2 = Redis::hsetnx('goods:102', 'discount', 0.8);
var_dump($isSuccess2); // bool(false)
```

### 4.13 哈希表分页（hpage）

```php
// 分页查询（第1页，每页5条）
$pageResult = Redis::hpage('goods:102', 1, 5);
var_dump($pageResult);
// array(5) { 
//   ["list"]=>array(5) { 字段值列表... } 
//   ["total"]=>int(7)  // 总字段数
//   ["page"]=>int(1)   // 当前页码
//   ["limit"]=>int(5)  // 每页条数
//   ["pages"]=>int(2)  // 总页数
// }
```

## 五、列表操作

### 5.1 插入元素（lpush）

支持头部（first）、尾部（last）插入，单个 / 多个元素

```php
// 尾部插入单个元素
Redis::lpush('queue:task', 'task1', 'last');

// 头部插入多个元素（数组形式）
Redis::lpush('queue:task', ['task0', 'task-1'], 'first');

// 尾部插入多个元素并设置过期时间（1800秒）
Redis::lpush('queue:task', ['task2', 'task3'], 'last', 1800);
```

### 5.2 通过索引获取元素（lindex）

```php
// 获取索引0的元素（头部第一个）
$firstTask = Redis::lindex('queue:task', 0);
var_dump($firstTask); // string(5) "task-1"

// 获取最后一个元素（索引-1）
$lastTask = Redis::lindex('queue:task', -1);
var_dump($lastTask); // string(5) "task3"
```

### 5.3 通过索引设置元素（lset）

```php
// 将索引2的元素改为 "task1_new"
$isSuccess = Redis::lset('queue:task', 2, 'task1_new');
var_dump($isSuccess); // bool(true)
```

### 5.4 获取区间元素（lrange）

```php
// 获取所有元素（0到-1）
$allTasks = Redis::lrange('queue:task', 0, -1);
var_dump($allTasks); // array(5) { [0]=>"task-1" [1]=>"task0" [2]=>"task1_new" [3]=>"task1" [4]=>"task3" }

// 获取索引1到3的元素
$partTasks = Redis::lrange('queue:task', 1, 3);
var_dump($partTasks); // array(3) { [0]=>"task0" [1]=>"task1_new" [2]=>"task1" }
```

### 5.5 获取列表长度（llen）

```php
$taskCount = Redis::llen('queue:task');
var_dump($taskCount); // int(5)
```

### 5.6 移出并获取元素（lpop）

支持头部（first）、尾部（last）

```php
// 移出并获取头部第一个元素
$popTask = Redis::lpop('queue:task');
var_dump($popTask); // string(5) "task-1"

// 移出并获取尾部最后一个元素
$popLastTask = Redis::lpop('queue:task', 'last');
var_dump($popLastTask); // string(5) "task3"
```

### 5.7 跨列表移动元素（lpoppush）

从列表 1 尾部弹出，插入列表 2 头部

```php
// 先创建列表2
Redis::lpush('queue:task:backup', 'backup-init', 'last
```