geckon01/predis
1
0
Fork 0
mirror of https://github.com/predis/predis.git synced 2026-09-20 15:26:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Partially rewrite README.

Browse Source 
[ci skip]
This commit is contained in:
Daniele Alessandri
2012-08-02 16:10:26 +02:00
parent c230b6e831
commit 81422b9992
1 changed files with 42 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+42 -32
View File
@@ -2,23 +2,21 @@
Predis is a flexible and feature-complete PHP (>= 5.3) client library for the Redis key-value store.
For a list of frequently asked questions about Predis, see the __FAQ__ file in the root of the repository.
For a version compatible with PHP 5.2 you must use the backported version from the latest release in the
0.6.x series. More details are available on the [official wiki](http://wiki.github.com/nrk/predis) of the
project.
For a list of frequently asked questions about Predis, see the __FAQ.md__ in the root of the repository.
More details are available on the [official wiki](http://wiki.github.com/nrk/predis) of the project.
## Main features ##
- Complete support for Redis from __1.2__ to __2.6__ and unstable versions using different server profiles.
- Wide range of Redis versions supported (from __1.2__ to __2.6__ and unstable) using server profiles.
- Smart support for [redis-cluster](http://redis.io/topics/cluster-spec) (Redis >= 3.0).
- Client-side sharding with support for consistent hashing or custom distribution strategies.
- Client-side sharding via consistent hashing or custom distribution strategies.
- Support for master / slave replication configurations (write on master, read from slaves).
- Command pipelining on single and aggregated connections.
- Transparent key prefixing strategy capable of handling any command known that has keys in its arguments.
- Command pipelining on single and aggregated connections.
- Abstraction for Redis transactions (Redis >= 2.0) with support for CAS operations (Redis >= 2.2).
- Abstraction for Lua scripting (Redis >= 2.6) capable of switching between EVAL and EVALSHA transparently.
- Connections to Redis instances are automatically and lazily estabilished upon the first call to a command.
- Abstraction for Lua scripting (Redis >= 2.6) capable of automatically switching between `EVAL` and `EVALSHA`.
- Connections to Redis instances are lazily estabilished upon the first call to a command by the client.
- Ability to connect to Redis using TCP/IP or UNIX domain sockets with support for persistent connections.
- Ability to use alternative connection classes to use different types of network or protocol backends.
- Flexible system to define and register your own set of commands or server profiles to client instances.
@@ -36,11 +34,11 @@ by browsing the list of [tagged releases](http://github.com/nrk/predis/tags).
### Loading the library ###
Predis relies on the autoloading features of PHP to automatically load the needed files and complies
with the [PSR-0 standard](http://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md) for
interoperability with most of the major frameworks and libraries. Everything is transparently handled
for you when installing the library using Composer, but you can also leverage its own autoloader class
if you are going to use it in a project or script without any PSR-0 compliant autoloading facility:
Predis relies on the autoloading features of PHP to load its files when needed and complies with the
[PSR-0 standard](http://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md) which makes it
compatible with most of the major frameworks and libraries. Autoloading in your application is handled
automatically when managing the dependencies with Composer, but you can also leverage its own autoloader
class if you are going to use it in a project or script without any PSR-0 compliant autoloading facility:
``` php
<?php
@@ -50,20 +48,19 @@ require 'Predis/Autoloader.php';
Predis\Autoloader::register();
```
You can create a single [Phar](http://www.php.net/manual/en/intro.phar.php) archive from the repository
just by launching the `bin/create-phar.php` executable script. The generated Phar archive ships with a
stub defining an autoloader function for Predis, so you just need to require the Phar to be able to use
the library.
It is possible to create a single [Phar](http://www.php.net/manual/en/intro.phar.php) archive from the
repository just by launching `bin/create-phar.php`. The generated Phar archive ships with a stub defining
an autoloader function for Predis, so you just need to require the Phar to be able to use the library.
Alternatively you can generate a single PHP file that holds every class, just like older versions of
Predis, using the `bin/create-single-file.php` executable script. In this way you can load Predis in your
scripts simply by using functions such as `require` and `include`, but this practice is not encouraged.
Alternatively it is possible to generate a single PHP file that holds every class, just like older versions
of Predis, using `bin/create-single-file.php`. In this way you can load Predis in your scripts simply by
using functions such as `require` and `include`, but this practice is not encouraged.
### Connecting to a local instance of Redis ###
### Connecting to Redis ###
When connecting to local instance of Redis (`127.0.0.1` on port `6379`), you do not have to specify any
additional parameter to create a new client instance:
By default Predis uses `127.0.0.1` and `6379` as the default host and port when creating a new client
instance without specifying any connection parameter:
``` php
<?php
@@ -72,7 +69,7 @@ $redis->set('foo', 'bar');
$value = $redis->get('foo');
```
However you can use an URI string or a named array to specify the needed connection parameters:
It is possible to specify the various connection parameters using URI strings or named arrays:
``` php
<?php
@@ -88,7 +85,7 @@ $redis = new Predis\Client(array(
```
### Pipelining multiple commands to multiple instances of Redis with client-side sharding ###
### Pipelining commands to multiple instances of Redis with client-side sharding ###
Pipelining helps with performances when there is the need to send many commands to a server in one go.
Furthermore, pipelining works transparently even on aggregated connections. To achieve this, Predis
@@ -111,11 +108,21 @@ $replies = $redis->pipeline(function ($pipe) {
```
### Overriding standard connection classes with custom ones ###
### Multiple and customizable connection backends ###
Predis allows developers to create new connection classes to add support for new protocols or override
the existing ones and provide a different implementation compared to the default classes. This can be
obtained by implementing `Predis\Connection\SingleConnectionInterface`.
Predis can optionally use different connection backends to connect to Redis. One of them leverages
the [phpiredis](http://github.com/seppo0010/phpiredis) C extension resulting in a major speed bump
especially when dealing with long multibulk replies (the `socket` extension is also required):
``` php
$client = new Predis\Client('tcp://127.0.0.1', array(
'connections' => array('tcp' => 'Predis\Connection\PhpiredisConnection')
));
```
Developers can also create their own connection backends to add support for new protocols, extend
existing ones or provide different implementations. Connection backend classes must implement
`Predis\Connection\SingleConnectionInterface` or extend `Predis\Connection\AbstractConnection`:
``` php
<?php
@@ -130,8 +137,8 @@ $client = new Predis\Client('tcp://127.0.0.1', array(
));
```
The classes contained in the `Predis\Connection` namespace give you a better insight with actual code
on how to create new connection classes.
For a more in-depth insight on how to create new connection backends you can look at the actual
implementation of the classes contained in `Predis\Connection` namespace.
### Defining and registering new commands on the client at runtime ###
@@ -188,6 +195,9 @@ on your newly created repository to fix or add features (possibly with tests cov
and then open a new pull request with a description of the applied changes. Obviously you can use any
other Git hosting provider of your preference.
Please also follow some basic [commit guidelines](http://git-scm.com/book/ch5-2.html#Commit-Guidelines)
before opening pull requests.
## Dependencies ##