Merge remote-tracking branch 'upstream/develop' into develop

Author: Gerardo Perosio

.travis.yml

@@ -5,8 +5,41 @@ php:
   - 5.4
   - 5.5
   - 5.6
-services: redis-server
-before_install: phpize
-install: ./configure --prefix=/usr && sudo make install
-before_script: echo 'extension = redis.so' >> ~/.phpenv/versions/$(phpenv version-name)/etc/php.ini
-script: php tests/TestRedis.php
+  - 7.0
+  - 7.1
+  - nightly
+env: CC=gcc
+matrix:
+  allow_failures:
+    - php: nightly
+  include:
+    - php: 5.4
+      env: CC=clang
+    - php: 5.5
+      env: CC=clang
+    - php: 5.6
+      env: CC=clang
+    - php: 7.0
+      env: CC=clang
+    - php: 7.1
+      env: CC=clang
+addons:
+  apt:
+    packages: clang
+before_install:
+  - phpize
+  - pecl install igbinary
+  - ./configure --enable-redis-igbinary CFLAGS=-Wall
+install: make install
+before_script:
+  - gem install redis
+  - mkdir -p tests/nodes/ && echo >> tests/nodes/nodemap
+  - for PORT in $(seq 6379 6382); do redis-server --port $PORT --daemonize yes; done
+  - for PORT in $(seq 7000 7011); do redis-server --port $PORT --cluster-enabled yes --cluster-config-file $PORT.conf --daemonize yes; echo 127.0.0.1:$PORT >> tests/nodes/nodemap; done
+  - wget https://raw.githubusercontent.com/antirez/redis/unstable/src/redis-trib.rb
+  - echo yes | ruby redis-trib.rb create --replicas 3 127.0.0.1:7000 127.0.0.1:7001 127.0.0.1:7002 127.0.0.1:7003 127.0.0.1:7004 127.0.0.1:7005 127.0.0.1:7006 127.0.0.1:7007 127.0.0.1:7008 127.0.0.1:7009 127.0.0.1:7010 127.0.0.1:7011
+  - echo 'extension = redis.so' >> ~/.phpenv/versions/$(phpenv version-name)/etc/php.ini
+script:
+  - php tests/TestRedis.php --class Redis
+  - php tests/TestRedis.php --class RedisArray
+  - php tests/TestRedis.php --class RedisCluster

README.markdown

@@ -5,7 +5,7 @@
 The phpredis extension provides an API for communicating with the [Redis](http://redis.io/) key-value store. It is released under the [PHP License, version 3.01](http://www.php.net/license/3_01.txt).
 This code has been developed and maintained by Owlient from November 2009 to March 2011.
 
-You can send comments, patches, questions [here on github](https://github.com/phpredis/phpredis/issues), to [email protected] ([@yowgi](http://twitter.com/yowgi)), or to [email protected] ([@grumi78](http://twitter.com/grumi78)).
+You can send comments, patches, questions [here on github](https://github.com/phpredis/phpredis/issues), to [email protected] ([@yowgi](https://twitter.com/yowgi)), to [email protected] ([@grumi78](https://twitter.com/grumi78)) or to [email protected] ([@yatsukhnenko](https://twitter.com/yatsukhnenko)).
 
 
 # Table of contents
@@ -82,7 +82,7 @@ You can install install it using Homebrew:
 phpredis can be used to store PHP sessions. To do this, configure `session.save_handler` and `session.save_path` in your php.ini to tell phpredis where to store the sessions:
 ~~~
 session.save_handler = redis
-session.save_path = "tcp://host1:6379?weight=1, tcp://host2:6379?weight=2&timeout=2.5, tcp://host3:6379?weight=2"
+session.save_path = "tcp://host1:6379?weight=1, tcp://host2:6379?weight=2&timeout=2.5, tcp://host3:6379?weight=2&read_timeout=2.5"
 ~~~
 
 `session.save_path` can have a simple `host:port` format too, but you need to provide the `tcp://` scheme if you want to use the parameters. The following parameters are available:
@@ -209,6 +209,7 @@ _**Description**_: Connects to a Redis instance.
 *timeout*: float, value in seconds (optional, default is 0 meaning unlimited)
 *reserved*: should be NULL if retry_interval is specified
 *retry_interval*: int, value in milliseconds (optional)
+*read_timeout*: float, value in seconds (optional, default is 0 meaning unlimited)
 
 ##### *Return value*
 
@@ -245,6 +246,7 @@ persistent equivalents.
 *timeout*: float, value in seconds (optional, default is 0 meaning unlimited)
 *persistent_id*: string. identity for the requested persistent connection
 *retry_interval*: int, value in milliseconds (optional)
+*read_timeout*: float, value in seconds (optional, default is 0 meaning unlimited)
 
 ##### *Return value*
 
@@ -1015,18 +1017,38 @@ _**Description**_:  Scan the keyspace for keys
 *LONG, Optional*: Count of keys per iteration (only a suggestion to Redis)
 
 ##### *Return value*
-*Array, boolean*:  This function will return an array of keys or FALSE if there are no more keys
+*Array, boolean*:  This function will return an array of keys or FALSE if Redis returned zero keys
 
 ##### *Example*
 ~~~
-$it = NULL; /* Initialize our iterator to NULL */
-$redis->setOption(Redis::OPT_SCAN, Redis::SCAN_RETRY); /* retry when we get no keys back */
-while($arr_keys = $redis->scan($it)) {
-    foreach($arr_keys as $str_key) {
+
+/* Without enabling Redis::SCAN_RETRY (default condition) */
+$it = NULL;
+do {
+    // Scan for some keys
+    $arr_keys = $redis->scan($it);
+
+    // Redis may return empty results, so protect against that
+    if ($arr_keys !== FALSE) {
+        foreach($arr_keys as $str_key) {
+            echo "Here is a key: $str_key\n";
+        }
+    }
+} while ($it > 0);
+echo "No more keys to scan!\n";
+
+/* With Redis::SCAN_RETRY enabled */
+$redis->setOption(Redis::OPT_SCAN, Redis::SCAN_RETRY);
+$it = NULL;
+
+/* phpredis will retry the SCAN command if empty results are returned from the
+   server, so no empty results check is required. */
+while ($arr_keys = $redis->scan($it)) {
+    foreach ($arr_keys as $str_key) {
         echo "Here is a key: $str_key\n";
     }
-    echo "No more keys to scan!\n";
 }
+echo "No more keys to scan!\n";
 ~~~
 
 ### object
@@ -1329,19 +1351,26 @@ $redis->restore('bar', 0, $val); // The key 'bar', will now be equal to the key
 ### migrate
 -----
 _**Description**_: Migrates a key to a different Redis instance.
+
+**Note:**: Redis introduced migrating multiple keys in 3.0.6, so you must have at least
+that version in order to call `migrate` with an array of keys.
+
 ##### *Parameters*
-*host* string.  The destination host
-*port* integer.  The TCP port to connect to.
-*key* string. The key to migrate.
-*destination-db* integer.  The target DB.
-*timeout* integer.  The maximum amount of time given to this transfer.
-*copy* boolean, optional.  Should we send the COPY flag to redis
-*replace* boolean, optional.  Should we send the REPLACE flag to redis
+*host* string.  The destination host  
+*port* integer.  The TCP port to connect to.  
+*key(s)* string or array.  
+*destination-db* integer.  The target DB.  
+*timeout* integer.  The maximum amount of time given to this transfer.  
+*copy* boolean, optional.  Should we send the COPY flag to redis.  
+*replace* boolean, optional.  Should we send the REPLACE flag to redis  
 ##### *Examples*
 ~~~
 $redis->migrate('backup', 6379, 'foo', 0, 3600);
 $redis->migrate('backup', 6379, 'foo', 0, 3600, true, true); /* copy and replace */
 $redis->migrate('backup', 6379, 'foo', 0, 3600, false, true); /* just REPLACE flag */
+
+/* Migrate multiple keys (requires Redis >= 3.0.6)
+$redis->migrate('backup', 6379, ['key1', 'key2', 'key3'], 0, 3600);
 ~~~
 
 
@@ -1362,6 +1391,7 @@ $redis->migrate('backup', 6379, 'foo', 0, 3600, false, true); /* just REPLACE fl
 * [hSetNx](#hsetnx) - Set the value of a hash field, only if the field does not exist
 * [hVals](#hvals) - Get all the values in a hash
 * [hScan](#hscan) - Scan a hash key for members
+* [hStrLen](#hstrlen) - Get the string length of the value associated with field in the hash
 
 ### hSet
 -----
@@ -1646,6 +1676,15 @@ while($arr_keys = $redis->hScan('hash', $it)) {
 }
 ~~~
 
+### hStrLen
+-----
+_**Description**_: Get the string length of the value associated with field in the hash stored at key.
+##### *Parameters*
+*key*: String
+*field*: String
+##### *Return value*
+*LONG* the string length of the value associated with field, or zero when field is not present in the hash or key does not exist at all.
+
 ## Lists
 
 * [blPop, brPop](#blpop-brpop) - Remove and get the first/last element in a list
@@ -2078,7 +2117,7 @@ $redis->lSize('key1');/* 2 */
 * [sIsMember, sContains](#sismember-scontains) - Determine if a given value is a member of a set
 * [sMembers, sGetMembers](#smembers-sgetmembers) - Get all the members in a set
 * [sMove](#smove) - Move a member from one set to another
-* [sPop](#spop) - Remove and return a random member from a set
+* [sPop](#spop) - Remove and return one or more members of a set at random
 * [sRandMember](#srandmember) - Get one or multiple random members from a set
 * [sRem, sRemove](#srem-sremove) - Remove one or more members from a set
 * [sUnion](#sunion) - Add multiple sets
@@ -2348,16 +2387,24 @@ $redis->sMove('key1', 'key2', 'member13'); /* 'key1' =>  {'member11', 'member12'
 _**Description**_: Removes and returns a random element from the set value at Key.
 ##### *Parameters*
 *key*
-##### *Return value*
+*count*: Integer, optional
+##### *Return value (without count argument)*
 *String* "popped" value
 *Bool* `FALSE` if set identified by key is empty or doesn't exist.
+##### *Return value (with count argument)*
+*Array*: Member(s) returned or an empty array if the set doesn't exist
+*Bool*: `FALSE` on error if the key is not a set
 ##### *Example*
 ~~~
 $redis->sAdd('key1' , 'member1');
 $redis->sAdd('key1' , 'member2');
 $redis->sAdd('key1' , 'member3'); /* 'key1' => {'member3', 'member1', 'member2'}*/
 $redis->sPop('key1'); /* 'member1', 'key1' => {'member3', 'member2'} */
 $redis->sPop('key1'); /* 'member3', 'key1' => {'member2'} */
+
+/* With count */
+$redis->sAdd('key2', 'member1', 'member2', 'member3');
+$redis->sPop('key2', 3); /* Will return all members but in no particular order */
 ~~~
 
 ### sRandMember

arrays.markdown

@@ -55,6 +55,13 @@ The connect_timeout value is a double and is used to specify a timeout in number
 $ra = new RedisArray(array("host1", "host2:63792", "host2:6380"), array("connect_timeout" => 0.5));
 </pre>
 
+#### Specifying the "read_timeout" parameter
+The read_timeout value is a double and is used to specify a timeout in number of seconds when waiting response from the server.
+<pre>
+$ra = new RedisArray(array("host1", "host2:63792", "host2:6380"), array("read_timeout" => 0.5));
+</pre>
+
+
 #### Defining arrays in Redis.ini
 
 Because php.ini parameters must be pre-defined, Redis Arrays must all share the same .ini settings.

cluster.markdown

@@ -13,15 +13,11 @@ To maintain consistency with the RedisArray class, one can create and connect to
 $obj_cluster = new RedisCluster(NULL, Array('host:7000', 'host:7001', 'host:7003'));
 
 // Connect and specify timeout and read_timeout
-$obj_cluster = new RedisCluster(
-    NULL, Array("host:7000", "host:7001"), 1.5, 1.5
-);
+$obj_cluster = new RedisCluster(NULL, Array("host:7000", "host:7001"), 1.5, 1.5);
 
 // Connect with read/write timeout as well as specify that phpredis should use
 // persistent connections to each node.
-$obj_cluster = new RedisCluster(
-    NULL, Array("host:7000", "host:7001"), 1.5, 1.5, true
-);
+$obj_cluster = new RedisCluster(NULL, Array("host:7000", "host:7001"), 1.5, 1.5, true);
 
 </pre>