Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Initial commit

  • Loading branch information...
commit 985967ba1dfeaf13731146cb0338b1e92bd797dc 0 parents
@salimane authored
4 .gitattributes
@@ -0,0 +1,4 @@
+Tests/ export-ignore
+phpunit.xml.dist export-ignore
+bin/ export-ignore
+.travis.yml export-ignore
7 .gitignore
@@ -0,0 +1,7 @@
+*.tgz
+*.phar
+phpunit.xml
+package.xml
+experiments/
+*.lock
+vendor
5 INSTALL
@@ -0,0 +1,5 @@
+
+Please check README.rst
+
+and report errors to Salimane Adjao Moustapha (me@salimane.com)
+
22 LICENSE
@@ -0,0 +1,22 @@
+Copyright (c) 2012 Salimane Adjao Moustapha
+
+ Permission is hereby granted, free of charge, to any person
+ obtaining a copy of this software and associated documentation
+ files (the "Software"), to deal in the Software without
+ restriction, including without limitation the rights to use,
+ copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following
+ conditions:
+
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ OTHER DEALINGS IN THE SOFTWARE.
3  MANIFEST.in
@@ -0,0 +1,3 @@
+include INSTALL
+include LICENSE
+include README.rst
230 README.rst
@@ -0,0 +1,230 @@
+rediscluster-php
+===============
+
+a PHP interface to a Cluster of Redis key-value stores.
+
+Project Goals
+-------------
+
+The goal of ``rediscluster-php``, together with `rediscluster-py <https://github.com/salimane/rediscluster-py.git>`_,
+is to have a consistent, compatible client libraries accross programming languages
+when sharding among different Redis instances in a transparent, fast, and
+fault tolerant way. ``rediscluster-php`` uses `phpredis <https://github.com/nicolasff/phpredis.git>`_
+when connecting to the redis servers, thus the original api commands would work without problems within
+the context of a cluster of redis servers.
+
+Travis CI
+---------
+
+Currently, ``rediscluster-php`` is being tested via travis ci for php
+version 5.3 and 5.4: |Build Status|
+
+Installation
+------------
+
+Download via `Composer <http://getcomposer.org/>`_
+Create a ``composer.json`` file if you don't already have one in your projects root directory and require rediscluster:
+
+::
+
+ {
+ "require": {
+ "rediscluster/rediscluster": "*"
+ }
+ }
+
+Install Composer:
+
+::
+
+ $ curl -s http://getcomposer.org/installer | php
+
+Run the install command:
+
+::
+
+ $ php composer.phar install
+
+This will download ``rediscluster`` into the `vendor/rediscluster/rediscluster` directory.
+To learn more about Composer visit http://getcomposer.org/
+
+Running Tests
+-------------
+
+::
+
+ $ git clone https://github.com/salimane/rediscluster-php.git
+ $ cd rediscluster-php
+ $ vi Tests/config.php
+ $ phpunit
+
+Getting Started
+---------------
+
+::
+
+ php -a
+ Interactive shell
+
+ php > require "/home/salimane/htdocs/rediscluster-php/vendor/autoload.php";
+ php > $cluster = array(
+ php ( //node names
+ php ( 'nodes' => array(
+ php ( //masters
+ php ( 'node_1' => array('host' => '127.0.0.1', 'port' => 63791),
+ php ( 'node_2' => array('host' => '127.0.0.1', 'port' => 63792),
+ php ( //slaves
+ php ( 'node_5' => array('host' => '127.0.0.1', 'port' => 63795),
+ php ( 'node_6' => array('host' => '127.0.0.1', 'port' => 63796),
+ php ( ),
+ php ( //replication information
+ php ( 'master_of' => array(
+ php ( 'node_1' => 'node_6', //node_6 slaveof node_1 in redis6.conf
+ php ( 'node_2' => 'node_5', // node_5 slaveof node_2 in redis5.conf
+ php ( ),
+ php (
+ php ( 'default_node' => 'node_1'
+ php ( );
+ php >
+ php > $r = new RedisCluster\RedisCluster($cluster, 4);
+ php > var_dump($r->set('foo', 'bar'));
+ bool(true)
+ php > var_dump($r->get('foo'));
+ string(3) "bar"
+
+
+Cluster Configuration
+---------------------
+
+The cluster configuration is a hash that is mostly based on the idea of a node, which is simply a host:port pair
+that points to a single redis-server instance. This is to make sure it doesn’t get tied it
+to a specific host (or port).
+The advantage of this is that it is easy to add or remove nodes from
+the system to adjust the capacity while the system is running.
+
+Read Slaves & Write Masters
+---------------------------
+
+``rediscluster`` uses master/slave mappings stored in the cluster hash passed during instantiation to
+transparently relay read redis commands to slaves and writes commands to masters.
+
+Partitioning Algorithm
+----------------------
+
+In order to map every given key to the appropriate Redis node, the algorithm used, based on crc32 and modulo, is :
+
+::
+
+ ((abs(crc32(<key>)) % <number of masters>) + 1)
+
+
+A function ``getnodefor`` is provided to get the node a particular key will be/has been stored to.
+
+::
+
+ php > print_r($r->getnodefor('foo'));
+ Array
+ (
+ [node_2] => Array
+ (
+ [host] => 127.0.0.1
+ [port] => 63792
+ )
+
+ )
+ php >
+
+Hash Tags
+-----------
+
+In order to specify your own hash key (so that related keys can all land
+on a given node), ``rediscluster`` allows you to pass a list where you’d normally pass a scalar.
+The first element of the list is the key to use for the hash and the
+second is the real key that should be fetched/modify:
+
+::
+
+ php > $r->get("bar{foo}")
+
+In that case “foo” is the hash key but “bar” is still the name of
+the key that is fetched from the redis node that “foo” hashes to.
+
+Multiple Keys Redis Commands
+----------------------------
+
+In the context of storing an application data accross many redis servers, commands taking multiple keys
+as arguments are harder to use since, if the two keys will hash to two different
+instances, the operation can not be performed. Fortunately, rediscluster is a little fault tolerant
+in that it still fetches the right result for those multi keys operations as far as the client is concerned.
+To do so it processes the related involved redis servers at interface level.
+
+::
+
+ php > foreach(array('b1', 'a2', 'b3') as $i) $r->sadd('bar', $i);
+ php > foreach(array('a1', 'a2', 'a3') as $i) $r->sadd('foo', $i);
+ php > var_dump($r->sdiffstore('foobar', 'foo', 'bar'));
+ int(2)
+ php >
+ php > print_r($r->smembers('foobar'));
+ Array
+ (
+ [0] => a1
+ [1] => a3
+ )
+ php >
+ php > print_r($r->getnodefor('foo'));
+ Array
+ (
+ [node_2] => Array
+ (
+ [host] => 127.0.0.1
+ [port] => 63792
+ )
+
+ )
+ php > print_r($r->getnodefor('bar'));
+ Array
+ (
+ [node_1] => Array
+ (
+ [host] => 127.0.0.1
+ [port] => 63791
+ )
+
+ )
+ php > print_r($r->getnodefor('foobar'));
+ Array
+ (
+ [node_2] => Array
+ (
+ [host] => 127.0.0.1
+ [port] => 63792
+ )
+
+ )
+ php >
+
+
+Redis-Sharding & Redis-Copy
+---------------------------
+
+In order to help with moving an application with a single redis server to a cluster of redis servers
+that could take advantage of ``rediscluster``, i wrote `redis-sharding <https://github.com/salimane/redis-tools#redis-sharding>`_
+and `redis-copy <https://github.com/salimane/redis-tools#redis-copy>`_
+
+Information
+-----------
+
+- Code: ``git clone git://github.com/salimane/rediscluster-php.git``
+- Home: http://github.com/salimane/rediscluster-php
+- Bugs: http://github.com/salimane/rediscluster-php/issues
+
+Author
+------
+
+``rediscluster-php`` is developed and maintained by Salimane Adjao Moustapha
+(me@salimane.com). It can be found here:
+http://github.com/salimane/rediscluster-php
+
+.. |Build Status| image:: https://secure.travis-ci.org/salimane/rediscluster-php.png?branch=master
+ :target: http://travis-ci.org/salimane/rediscluster-php
Please sign in to comment.
Something went wrong with that request. Please try again.