README

PHP >= 5.3 和 HHVM >= 2.3.0 的灵活且功能齐全的 Redis 客户端。

Predis 默认不需要任何额外的 C 扩展，但可以选择与 phpiredis 配对以降低 Redis RESP 协议的序列化和解析开销。

有关此项目的更多详细信息，请参阅常见问题解答。

主要功能

通过配置文件支持不同版本的 Redis（从 2.0 到 3.2）。
支持使用客户端分片和可插拔键空间分发器的集群。
支持 redis-cluster（Redis >= 3.0）。
支持主从复制设置和 redis-sentinel。
使用可定制的策略实现键的透明键前缀。
在单个节点和集群（仅客户端分片）上支持命令管道。
Redis 事务（Redis >= 2.0）和 CAS 操作（Redis >= 2.2）的抽象。
Redis >= 2.6 的 Lua 脚本的抽象，并自动在 EVALSHA 或 EVAL 之间切换。
基于 PHP 迭代器的 SCAN、SSCAN、ZSCAN 和 HSCAN（Redis >= 2.8）的抽象。
客户端在首次执行命令时建立连接，并且可以持久化连接。
可以通过 TCP/IP（也支持 TLS/SSL 加密）或 UNIX 域套接字建立连接。
支持 Webdis（需要 ext-curl 和 ext-phpiredis 扩展）。
支持自定义连接类，以提供不同的网络或协议后端。
灵活的系统来定义自定义命令和配置文件，并覆盖默认值。

如何安装和使用 Predis

此库可以在 Packagist 上找到，便于使用 Composer 管理项目依赖，或者在我们的 PEAR 频道上以更传统的安装方式使用 PEAR。最终，每个版本的压缩归档都可以在 GitHub 上找到。

加载库

Predis 依赖于 PHP 的自动加载功能，在需要时加载其文件，并符合 PSR-4 标准。当通过 Composer 管理依赖时，自动加载会自动处理，但在缺乏任何自动加载功能的项目或脚本中，也可以利用其自带的自动加载器。

// Prepend a base path if Predis is not available in your "include_path".
require 'Predis/Autoloader.php';

Predis\Autoloader::register();

还可以通过运行 bin/create-phar 脚本直接从仓库创建一个 phar 归档。生成的 phar 已经包含一个定义其自己的自动加载器的存根，因此您只需 require() 它即可开始使用库。

连接到 Redis

在创建不传递任何连接参数的客户端实例时，Predis默认将127.0.0.1和6379作为主机和端口。默认的connect()操作超时时间为5秒。

$client = new Predis\Client();
$client->set('foo', 'bar');
$value = $client->get('foo');

连接参数可以以URI字符串或命名数组的形式提供。后者是提供参数的首选方式，但在从非结构化或部分结构化的来源读取参数时，URI字符串可能很有用。

// Parameters passed using a named array:
$client = new Predis\Client([
    'scheme' => 'tcp',
    'host'   => '10.0.0.1',
    'port'   => 6379,
]);

// Same set of parameters, passed using an URI string:
$client = new Predis\Client('tcp://10.0.0.1:6379');

可以通过将password添加到参数集中来访问受密码保护的服务器。当Redis >= 6.0上启用了ACL时，用户认证需要username和password。

还可以使用UNIX域套接字连接到本地的Redis实例，在这种情况下，参数必须使用unix方案并指定套接字文件的路径。

$client = new Predis\Client(['scheme' => 'unix', 'path' => '/path/to/redis.sock']);
$client = new Predis\Client('unix:/path/to/redis.sock');

客户端可以利用TLS/SSL加密连接到安全的远程Redis实例，而无需配置像stunnel这样的SSL代理。当连接到运行在各个云托管提供商上的节点时，这可能很有用。可以通过使用tls方案并传递一个包含合适选项的数组来启用加密，这些选项通过ssl参数传递。

// Named array of connection parameters:
$client = new Predis\Client([
  'scheme' => 'tls',
  'ssl'    => ['cafile' => 'private.pem', 'verify_peer' => true],
]);

// Same set of parameters, but using an URI string:
$client = new Predis\Client('tls://127.0.0.1?ssl[cafile]=private.pem&ssl[verify_peer]=1');

还支持连接方案redis（tcp的别名）和rediss（tls的别名），这两种方案的区别在于包含这些方案的URI字符串的解析遵循它们各自的IANA临时注册文件中描述的规则。

支持的实际连接参数列表可能因每个连接后端而异，因此建议参考它们的特定文档或实现以获取详细信息。

当提供连接参数数组时，Predis会自动在集群模式下使用客户端分片工作。在为每个节点提供配置时，可以混合命名数组和URI字符串。

$client = new Predis\Client([
    'tcp://10.0.0.1?alias=first-node',
    ['host' => '10.0.0.2', 'alias' => 'second-node'],
]);

有关详细信息，请参阅本文件的聚合连接部分。

连接到Redis是懒加载的，这意味着客户端仅在需要时才连接到服务器。虽然建议让客户端在底层自行处理，但在某些情况下，可能仍然希望控制连接何时打开或关闭：这可以通过调用$client->connect()和$client->disconnect()轻松实现。请注意，这些方法对聚合连接的影响可能因具体实现而异。

客户端配置

可以通过向Predis\Client::__construct()的第二个参数传递特定的客户端选项来配置客户端的许多方面和行为。

$client = new Predis\Client($parameters, ['profile' => '2.8', 'prefix' => 'sample:']);

选项使用类似于DI的容器进行管理，并且它们的值只有在需要时才会懒加载。Predis默认支持的客户端选项包括

profile：指定用于匹配特定Redis版本的配置文件。
prefix：自动应用于命令中找到的键的前缀字符串。
exceptions：客户端是否在Redis错误时抛出或返回响应。
connections：连接后端列表或连接工厂实例。
cluster：指定集群后端（predis、redis或可调用对象）。
replication：指定复制后端（TRUE、sentinel或可调用对象）。
aggregate：覆盖cluster和replication以提供自定义连接聚合器。
parameters：聚合连接的默认连接参数列表。

用户还可以提供自定义选项，这些选项具有值或可调用对象（用于懒加载），并存储在选项容器中以供稍后通过库使用。

聚合连接

聚合连接是Predis实现集群和复制的基石，它们用于将多个连接分组到单个Redis节点，并隐藏根据上下文正确处理它们的特定逻辑。创建新的客户端实例通常需要一个连接参数数组。

集群

默认情况下，如果没有设置特定的客户端选项，并且将连接参数数组传递给客户端构造函数，Predis会配置自己以集群模式工作，使用传统的客户端端分片方法创建一个独立节点的集群，并将键空间分布在它们之间。这种方法需要节点外部健康监控的形式，并且需要在更改配置时通过添加或删除节点进行手动操作以重新平衡键空间。

$parameters = ['tcp://10.0.0.1', 'tcp://10.0.0.2', 'tcp://10.0.0.3'];

$client = new Predis\Client($parameters);

随着Redis 3.0的推出，一种新的监控和协调类型的集群以redis-cluster的形式被引入。这种方法的算法不同，用于分布键空间，Redis节点通过Gossip协议进行通信以协调自身，以处理健康状态、重新平衡、节点发现和请求重定向。为了连接到由redis-cluster管理的集群，客户端需要一个节点列表（可能不是完整的，因为如果需要，它将自动发现新节点），并将cluster客户端选项设置为redis。

$parameters = ['tcp://10.0.0.1', 'tcp://10.0.0.2', 'tcp://10.0.0.3'];
$options    = ['cluster' => 'redis'];

$client = new Predis\Client($parameters, $options);

复制

客户端可以被配置为在单个主服务器/多个从服务器设置中运行，以提供更好的服务可用性。在使用复制时，Predis识别只读命令并将它们发送到随机从服务器，以提供某种形式的负载均衡，并在检测到执行任何修改键空间或键值的命令时切换到主服务器。当从服务器失败时，客户端不会引发连接错误，而是尝试回退到配置中提供的其他从服务器。

使用客户端在复制模式下所需的基本配置需要将一个Redis服务器标识为主服务器（这可以通过使用alias参数设置为master的连接参数来完成），以及一个或多个充当从服务器的服务器。

$parameters = ['tcp://10.0.0.1?alias=master', 'tcp://10.0.0.2', 'tcp://10.0.0.3'];
$options    = ['replication' => true];

$client = new Predis\Client($parameters, $options);

上述配置具有静态服务器列表，完全依赖于客户端的逻辑，但可以使用redis-sentinel来依靠一个更健壮的HA环境，其中sentinel服务器作为客户端的服务发现权威源。客户端与redis-sentinel一起工作所需的最小配置是一个指向一组sentinel实例的连接参数列表，将replication选项设置为sentinel，并将service选项设置为服务的名称。

$sentinels = ['tcp://10.0.0.1', 'tcp://10.0.0.2', 'tcp://10.0.0.3'];
$options   = ['replication' => 'sentinel', 'service' => 'mymaster'];

$client = new Predis\Client($sentinels, $options);

如果主从节点被配置为需要客户端的认证，则必须通过全局parameters客户端选项提供密码。此选项还可以用于指定不同的数据库索引。客户端选项数组将如下所示

$options = [
    'replication' => 'sentinel',
    'service' => 'mymaster',
    'parameters' => [
        'password' => $secretpassword,
        'database' => 10,
    ],
];

虽然Predis能够区分执行写操作和只读操作的命令，但EVAL和EVALSHA代表一个角落案例，其中客户端切换到主节点，因为它无法判断Lua脚本何时可以在从服务器上安全执行。虽然这确实是默认行为，但当某些Lua脚本不执行写操作时，可以提供一个提示告诉客户端在执行时坚持使用从服务器。

$parameters = ['tcp://10.0.0.1?alias=master', 'tcp://10.0.0.2', 'tcp://10.0.0.3'];
$options    = ['replication' => function () {
    // Set scripts that won't trigger a switch from a slave to the master node.
    $strategy = new Predis\Replication\ReplicationStrategy();
    $strategy->setScriptReadOnly($LUA_SCRIPT);

    return new Predis\Connection\Aggregate\MasterSlaveReplication($strategy);
}];

$client = new Predis\Client($parameters, $options);
$client->eval($LUA_SCRIPT, 0);             // Sticks to slave using `eval`...
$client->evalsha(sha1($LUA_SCRIPT), 0);    // ... and `evalsha`, too.

examples目录包含一些脚本，演示了如何配置和使用客户端在基本和复杂场景中利用复制。

命令管道

流水线可以提升性能，特别是在需要向服务器发送大量命令时，通过减少网络往返时延来降低延迟。流水线还适用于聚合连接。客户端可以在可调用块中执行流水线，或者通过其流畅的接口返回一个具有链式命令能力的流水线实例

// Executes a pipeline inside the given callable block:
$responses = $client->pipeline(function ($pipe) {
    for ($i = 0; $i < 1000; $i++) {
        $pipe->set("key:$i", str_pad($i, 4, '0', 0));
        $pipe->get("key:$i");
    }
});

// Returns a pipeline that can be chained thanks to its fluent interface:
$responses = $client->pipeline()->set('foo', 'bar')->get('foo')->execute();

事务

客户端提供了一种基于 MULTI 和 EXEC 的 Redis 事务抽象，其接口与命令流水线类似

// Executes a transaction inside the given callable block:
$responses = $client->transaction(function ($tx) {
    $tx->set('foo', 'bar');
    $tx->get('foo');
});

// Returns a transaction that can be chained thanks to its fluent interface:
$responses = $client->transaction()->set('foo', 'bar')->get('foo')->execute();

该抽象可以通过 WATCH 和 UNWATCH 执行检查和设置操作，并在 WATCH 的键被触摸时自动重试 Redis 中终止的事务。关于使用 CAS 的交易示例，您可以查看以下示例。

添加新命令

虽然我们努力更新 Predis 以保持与 Redis 中所有可用命令同步，但您可能更愿意坚持使用库的旧版本或提供不同的方法来过滤特定命令的参数或解析响应。为了实现这一点，Predis 提供了实现新命令类的功能，以在客户端使用的默认服务器配置中定义或覆盖命令

// Define a new command by extending Predis\Command\Command:
class BrandNewRedisCommand extends Predis\Command\Command
{
    public function getId()
    {
        return 'NEWCMD';
    }
}

// Inject your command in the current profile:
$client = new Predis\Client();
$client->getProfile()->defineCommand('newcmd', 'BrandNewRedisCommand');

$response = $client->newcmd();

还有一个方法可以发送原始命令，而不过滤它们的参数或解析响应。用户必须以数组形式提供命令的参数列表，遵循Redis 命令文档中定义的签名

$response = $client->executeRaw(['SET', 'foo', 'bar']);

脚本命令

虽然可以直接使用 Lua 脚本和 EVAL 以及 EVALSHA 来利用 Redis 2.6+ 上的 Lua 脚本，但 Predis 提供了脚本命令作为基于它们的更高级抽象，以简化操作。脚本命令可以注册到客户端使用的服务器配置中，并且可以像普通 Redis 命令一样访问，但它们定义了传输到服务器进行远程执行的 Lua 脚本。内部默认使用 EVALSHA 并通过脚本的 SHA1 哈希值来标识脚本以节省带宽，但在需要时使用 EVAL 作为后备

// Define a new script command by extending Predis\Command\ScriptCommand:
class ListPushRandomValue extends Predis\Command\ScriptCommand
{
    public function getKeysCount()
    {
        return 1;
    }

    public function getScript()
    {
        return <<<LUA
math.randomseed(ARGV[1])
local rnd = tostring(math.random())
redis.call('lpush', KEYS[1], rnd)
return rnd
LUA;
    }
}

// Inject the script command in the current profile:
$client = new Predis\Client();
$client->getProfile()->defineCommand('lpushrand', 'ListPushRandomValue');

$response = $client->lpushrand('random_values', $seed = mt_rand());

可定制的连接后端

Predis 可以使用不同的连接后端来连接到 Redis。其中两个利用第三方扩展，如 phpiredis，在处理大型多批量响应时可以实现重大性能提升。其中一个是基于 PHP 流，另一个是基于由 ext-socket 提供的套接字资源。两者都支持 TCP/IP 和 UNIX 域套接字

$client = new Predis\Client('tcp://127.0.0.1', [
    'connections' => [
        'tcp'  => 'Predis\Connection\PhpiredisStreamConnection',  // PHP stream resources
        'unix' => 'Predis\Connection\PhpiredisSocketConnection',  // ext-socket resources
    ],
]);

开发人员可以创建自己的连接类以支持全新的网络后端，扩展现有类或提供完全不同的实现。连接类必须实现 Predis\Connection\NodeConnectionInterface 或扩展 Predis\Connection\AbstractConnection

class MyConnectionClass implements Predis\Connection\NodeConnectionInterface
{
    // Implementation goes here...
}

// Use MyConnectionClass to handle connections for the `tcp` scheme:
$client = new Predis\Client('tcp://127.0.0.1', [
    'connections' => ['tcp' => 'MyConnectionClass'],
]);

有关如何创建新的连接后端的更深入的了解，您可以参考 Predis\Connection 命名空间中可用的标准连接类的实际实现。

开发

报告错误和贡献代码

对于Predis的贡献，无论是以新功能、错误修复还是仅错误报告的形式，我们都非常欢迎。我们只要求你在提交更改或在问题跟踪器上报告错误之前，遵循一套基本规则，以便让每个人在项目工作中保持一致性。

测试套件

注意：请勿在生产环境中运行Predis附带测试套件，或运行包含你感兴趣数据的Redis实例！

Predis具有全面的测试套件，覆盖库的各个方面。该测试套件会对Redis运行实例（需要>= 2.4.0）进行集成测试，以验证每个命令实现的正确性，并自动跳过在指定的Redis配置文件中未定义的命令。如果你没有运行Redis，可以禁用集成测试。默认情况下，测试套件配置为使用Redis 3.2（Redis的当前稳定版本）配置文件执行集成测试，但可以通过修改phpunit.xml并将REDIS_SERVER_VERSION设置为dev来选择性地针对从unstable分支构建的Redis实例。有关测试Predis的更详细信息，请参阅测试README。

Predis使用Travis CI进行持续集成，过去和当前的构建历史可以在其项目页面上找到。

kornrunner / predis

维护者

详细信息

README

主要功能

如何安装和使用 Predis

加载库

连接到 Redis

客户端配置

聚合连接

集群

复制

命令管道

事务

添加新命令

脚本命令

可定制的连接后端

开发

报告错误和贡献代码

测试套件

其他

项目相关链接

作者

许可协议

kornrunner / predis

维护者

详细信息

README

主要功能

如何 安装 和使用 Predis

加载库

连接到 Redis

客户端配置

聚合连接

集群

复制

命令管道

事务

添加新命令

脚本命令

可定制的连接后端

开发

报告错误和贡献代码

测试套件

其他

项目相关链接

作者

许可协议

如何安装和使用 Predis