simple-redis

hongxunpan/simple-redis 为 hongxunpan/simple-framework 提供可按需安装、显式启用的 Redis 运行时集成。

本包负责：

• 加载并校验标准 Redis 配置；
• 把 HongXunPan\DB\Redis\Redis 绑定为容器单例；
• 在 Module 启动阶段调用 setAsGlobal()，让新实例入口与旧静态入口复用同一连接池；
• 提供可显式发布的安全配置模板。

本包不实现 Redis Manager，不包含 Event Driver，也不提供全局 redis() helper。 命名连接、延迟创建和底层 phpredis 适配由 hongxunpan/db 提供。

安装与启用

composer require hongxunpan/simple-redis
php bin/simple module:enable redis

安装 Composer 包不会自动启用 Module。启用后，Provider 只构造并登记 Redis 实例， 不会立即建立网络连接；首次取得连接时才会连接 Redis。

默认配置

默认 Loader 读取 config('redis')。项目没有提供该配置时，使用包内安全模板：

return [
    'connections' => [
        'default' => [
            'host' => env('REDIS_HOST', '127.0.0.1'),
            'port' => (int) env('REDIS_PORT', 6379),
            'auth' => null,
            'database' => 0,
            'scheme' => 'tcp',
        ],
    ],
];

配置只包含 Redis 连接信息。events.*、stream、consumer group 等事件运输参数不属于本包。 无参数调用固定使用保留连接名 default，因此标准配置必须包含该名称。

如需在项目侧生成可定制配置：

php bin/simple module:publish redis config

发布操作只创建不存在的 config/redis.php，不会覆盖项目已定制文件。

使用连接

推荐从容器取得实例：

use HongXunPan\DB\Redis\Redis;

$redis = app(Redis::class);
$redis->getConnection()->set('key', 'value');
$redis->getConnection('cache')->get('key');

旧静态入口会代理到同一实例：

Redis::connection()->set('key', 'value');

取得缓存连接时不会隐藏执行 PING。需要主动重建时使用：

$redis->reconnect('cache');

项目侧覆盖

redis.* 只是默认 Loader 的配置名称，不是 Module 强制业务契约。项目可以在 config('module.provider-override') 中登记自己的 Provider，然后覆盖：

• RedisConfigLoader：从任意配置结构加载并转换为标准对象；
• RedisConfig：直接提供已经校验的命名连接；
• Redis：替换完整连接实例或测试适配。

示例：

use HongXunPan\Framework\Core\Application;
use HongXunPan\Framework\Provider\ServiceProvider;
use HongXunPan\SimpleRedis\Config\RedisConfig;

final class ProjectRedisProvider extends ServiceProvider
{
    public function register(Application $app): void
    {
        $app->instance(RedisConfig::class, RedisConfig::fromArray([
            'connections' => [
                'default' => [
                    'host' => 'redis.internal',
                    'port' => 6379,
                ],
            ],
        ]));
    }
}

项目 Provider 在 Module Provider 之后注册，RedisServiceProvider::boot() 会接管项目最终绑定的 Redis 实例。

配置边界

标准连接配置支持：

• host、port、timeout；
• persistent、persistent_id；
• retry_interval、read_timeout；
• context、scheme=tcp|tls；
• auth，使用密码字符串或 [username, password]；
• database、prefix、options。

simple-redis 会拒绝未知配置键和旧式键名。旧 reserved、retryInterval、 readTimeout 等兼容转换只保留在 hongxunpan/db 的旧入口中，不进入新 Module 契约。

验证

composer test

测试覆盖 Module 元数据、标准配置校验、默认 Loader、项目配置覆盖、延迟连接和全局实例接管。