geckon01/predis
1
0
Fork 0
mirror of https://github.com/predis/predis.git synced 2026-09-12 03:17:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update README.

Browse Source 
[ci skip]
This commit is contained in:
Daniele Alessandri
2014-07-27 15:41:06 +02:00
parent 776f5831a6
commit 44c9232b13
1 changed files with 35 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+35 -35
View File
@@ -11,8 +11,8 @@ Redis protocol. An asynchronous implementation of the client, albeit experimenta
through [Predis\Async](https://github.com/nrk/predis-async).
Predis can be used with [HHVM](http://www.hhvm.com) >= 2.3.0, but there are no guarantees you will
not run into unexpected issues (especially with the JIT compiler enabled via `Eval.Jit = true`) due
to HHVM being still under heavy development, thus unstable and not yet 100% compatible with PHP.
not run into unexpected issues (especially when the JIT compiler is enabled via `Eval.Jit = true`)
due to HHVM being still under heavy development, thus unstable and not yet 100% compatible with PHP.
More details about the project can be found in our [frequently asked questions](FAQ.md) section or
on the online [wiki](https://github.com/nrk/predis/wiki).
@@ -21,11 +21,11 @@ on the online [wiki](https://github.com/nrk/predis/wiki).
## Main features ##
- Wide range of Redis versions supported (from __2.0__ to __3.0__ and __unstable__) using profiles.
- Clustering via client-side sharding using consistent hashing or custom distributors.
- Cluster of nodes via client-side sharding using consistent hashing or custom distributors.
- Smart support for [redis-cluster](http://redis.io/topics/cluster-tutorial) (Redis >= 3.0).
- Support for master-slave replication configurations (write on master, read from slaves).
- Transparent key prefixing for all known Redis commands using a customizable prefixing strategy.
- Command pipelining (works on both single and aggregate connections).
- Command pipelining (works on both single nodes and aggregate connections).
- Abstraction for Redis transactions (Redis >= 2.0) supporting CAS operations (Redis >= 2.2).
- Abstraction for Lua scripting (Redis >= 2.6) with automatic switching between `EVALSHA` or `EVAL`.
- Abstraction for `SCAN`, `SSCAN`, `ZSCAN` and `HSCAN` (Redis >= 2.8) based on PHP iterators.
@@ -48,8 +48,8 @@ Ultimately, archives of each release are [available on GitHub](https://github.co
Predis relies on the autoloading features of PHP to load its files when needed and complies with the
[PSR-4 standard](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md).
Autoloading is handled automatically when dependencies are managed using Composer, but you can also
leverage its own autoloader when using it in a project or script without any autoloading facility:
Autoloading is handled automatically when dependencies are managed through Composer, but it is also
possible to leverage its own autoloader in projects or scripts not having any autoload facility:
```php
// Prepend a base path if Predis is not available in your "include_path".
@@ -61,14 +61,14 @@ Predis\Autoloader::register();
It is possible to easily create a [phar](http://www.php.net/manual/en/intro.phar.php) archive from
the repository just by launching `bin/create-phar`. The generated phar contains a stub defining an
autoloader function for Predis, so you just need to require the phar to start using the library.
Alternatively, it is also possible to generate one single PHP file that holds every class like older
versions of Predis by launching `bin/create-single-file`, but this practice __is not__ encouraged.
Alternatively it is possible to generate one single PHP file holding every class like older versions
of Predis by launching `bin/create-single-file`, but this practice __is not__ encouraged.
### Connecting to Redis ###
When not specifying any connection parameter to create a new client, Predis assumes `127.0.0.1` and
`6379` as the default host and port and uses a connection timeout of 5 seconds:
`6379` as the default host and port with a connection timeout of 5 seconds:
```php
$client = new Predis\Client();
@@ -92,9 +92,9 @@ $client = new Predis\Client([
$client = new Predis\Client('tcp://10.0.0.1:6379');
```
When an array of connections parameters is provided, Predis automatically works in clustering mode
using client-side sharding. Both named arrays and URI strings can be mixed for providing each node
configuration:
When an array of connection parameters is provided, Predis automatically works in cluster mode using
client-side sharding. Both named arrays and URI strings can be mixed when providing configurations
for each node:
```php
$client = new Predis\Client([
@@ -104,12 +104,12 @@ $client = new Predis\Client([
```
The actual list of supported connection parameters can vary depending on each connection backend so
it is recommended to refer to their specific documentation for details.
it is recommended to refer to their specific documentation or implementation for details.
### Client configuration ###
Various aspects of the client can be easily configured by passing options to the second argument of
Various aspects of the client can be configured simply by passing options to the second argument of
`Predis\Client::__construct()`. Options are managed using a mini DI-alike container and their values
are usually lazily initialized only when needed. Predis by default supports the following options:
@@ -127,11 +127,12 @@ the options container for later use through the library.
### Aggregate connections ###
Predis is able to aggregate multiple connections which is the base for clustering and replication.
By default the client implements clustering using either client-side sharding (default) or a Redis
backed solution using [redis-cluster](http://redis.io/topics/cluster-tutorial). As for replication,
Predis can handle single-master and multiple-slaves setups by executing read operations on slaves
and switching to the master for write operations. The replication behavior is fully configurable.
Predis is able to aggregate multiple connections which is the base for cluster and replication. By
default the client implements a cluster of nodes using either client-side sharding (default) or a
Redis-backed solution using [redis-cluster](http://redis.io/topics/cluster-tutorial).
As for replication, Predis can handle a single-master and multiple-slaves setup by executing read
operations on slaves and switching to the master for write operations. The replication behavior is
fully configurable.
#### Replication ####
@@ -156,28 +157,27 @@ the client to stick with slaves for their execution.
```php
$parameters = ['tcp://10.0.0.1?alias=master', 'tcp://10.0.0.2?alias=slave-01'];
$options = ['replication' => function () {
// Set scripts that won't trigger a switch from a slave to the master node.
$strategy = new Predis\Replication\ReplicationStrategy();
// This exact script won't trigger a switch from a slave to the master node.
$strategy->setScriptReadOnly($READONLY_LUA_SCRIPT);
$strategy->setScriptReadOnly($LUA_SCRIPT);
return new Predis\Connection\Aggregate\MasterSlaveReplication($strategy);
}];
$client = new Predis\Client($parameters, $options);
$client->eval($READONLY_LUA_SCRIPT, 0); // Sticks to slave using `eval`...
$client->evalsha(sha1($READONLY_LUA_SCRIPT), 0); // ... and `evalsha`, too.
$client->eval($LUA_SCRIPT, 0); // Sticks to slave using `eval`...
$client->evalsha(sha1($LUA_SCRIPT), 0); // ... and `evalsha`, too.
```
The `examples` directory contains two complete scripts showing how replication can be configured for
[simple](examples/replication_simple.php) or [complex](examples/replication_complex.php) scenarios.
#### Clustering ####
#### Cluster ####
Simply passing an array of connection parameters to the client constructor configures Predis to work
in clustering mode using client-side sharding. If you, on the other hand, want to leverage Redis >=
3.0 nodes coordinated by redis-cluster, then the client must be initialized like this:
in cluster mode using client-side sharding. If you, on the other hand, want to leverage Redis >= 3.0
nodes coordinated by redis-cluster, then the client must be initialized like this:
```php
$parameters = ['tcp://10.0.0.1', 'tcp://10.0.0.2'];
@@ -186,9 +186,9 @@ $options = ['cluster' => 'redis'];
$client = new Predis\Client($parameters, $options);
```
When using redis-cluster, it is not necessary to pass all of the nodes forming your cluster but you
can simply specify only a few nodes and Predis will automatically fetch the full and updated slots
map directly from Redis by contacting one of the nodes.
When using redis-cluster, it is not necessary to pass all of the nodes that compose your cluster but
you can simply specify only a few nodes: Predis will automatically fetch the full and updated slots
map directly from Redis by contacting one of the servers.
__NOTE__: our support for redis-cluster does not currently consider master / slave replication but
this feature will be added in a future release of this library.
@@ -260,9 +260,9 @@ $client->getProfile()->defineCommand('newcmd', 'BrandNewRedisCommand');
$response = $client->newcmd();
```
There is also a method to allow sending raw commands without filtering their arguments or parsing
responses. Users must provide the arguments list as an array, following the command signatures as
defined by the [Redis documentation for commands](http://redis.io/commands):
There is also a method to send raw commands without filtering their arguments or parsing responses.
Users must provide the arguments list as an array, following the command signatures as defined by
the [Redis documentation for commands](http://redis.io/commands):
```php
$response = $client->executeRaw(['SET', 'foo', 'bar']);
@@ -300,7 +300,7 @@ LUA;
}
}
// Inject your scriptable command in the current profile:
// Inject your script command in the current profile:
$client = new Predis\Client();
$client->getProfile()->defineCommand('lpushrand', 'ListPushRandomValue');
@@ -324,7 +324,7 @@ $client = new Predis\Client('tcp://127.0.0.1', [
]);
```
Developers can create their own connection classes to add support for new network backends, extend
Developers can create their own connection classes to support whole new network backends, extend
existing ones or provide completely different implementations. Connection classes must implement
`Predis\Connection\NodeConnectionInterface` or extend `Predis\Connection\AbstractConnection`: