Documentation: More docblocks with examples.

4 files changed, 318 insertions, 22 deletions

diff --git a/redis.stub.php b/redis.stub.php
index aad71f3d..39e94ad0 100644
--- a/redis.stub.php
+++ b/redis.stub.php
@@ -1215,29 +1215,321 @@ class Redis {
      */
     public function hGetAll(string $key): Redis|array|false;
 
-    public function hIncrBy(string $key, string $member, int $value): Redis|int|false;
+    /**
+     * Increment a hash field's value by an integer
+     *
+     * @see https://redis.io/commands/hincrby
+     *
+     * @param string $key   The hash to modify
+     * @param string $field The field to increment
+     * @param int    $value How much to increment the value.
+     *
+     * @return Redis|int|false The new value of the field.
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->del('player');
+     *
+     * $redis->hmset('player', ['name' => 'Bob', 'level' => 1]);
+     *
+     * // int(2)
+     * $redis->hIncrBy('player', 'level', 1);
+     *
+     * // int(5)
+     * $redis->hIncrBy('player', 'level', 3);
+     * ?>
+     * </code>
+     *
+     */
+    public function hIncrBy(string $key, string $field, int $value): Redis|int|false;
 
-    public function hIncrByFloat(string $key, string $member, float $value): Redis|float|false;
+    /**
+     * Increment a hash field by a floating point value
+     *
+     * @see https://redis.io/commands/hincrbyfloat
+     *
+     * @param string $key The hash with the field to increment.
+     * @param string $field The field to increment.
+     *
+     * @return Redis|float|false The field value after incremented.
+     *
+     * <code>
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->del('trig-numbers')
+     *
+     * // float(3.1415926)
+     * $pi = $redis->hIncrByFloat('trig-numbers', 'pi', 3.1415926);
+     *
+     * // float(6.2831852)
+     * $redis->hIncrByFloat('trig-numbers', 'tau', 2 * $pi);
+     * ?>
+     * </code>
+     */
+    public function hIncrByFloat(string $key, string $field, float $value): Redis|float|false;
 
+    /**
+     * Retrieve all of the fields of a hash.
+     *
+     * @see https://redis.io/commands/hkeys
+     *
+     * @param string $key The hash to query.
+     *
+     * @return Redis|array|false The fields in the hash or false if the hash doesn't exist.
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->del('ships');
+     *
+     * $redis->hmset('ships', ['Enterprise' => 'NCC-1701D', 'Defiant' => 'NX-74205', 'Voyager' => 'NCC-74656']);
+     *
+     * // array(3) {
+     * //   [0]=>
+     * //   string(10) "Enterprise"
+     * //   [1]=>
+     * //   string(7) "Defiant"
+     * //   [2]=>
+     * //   string(7) "Voyager"
+     * // }
+     * $redis->hKeys('ships');
+     * ?>
+     * </code>
+     */
     public function hKeys(string $key): Redis|array|false;
 
+    /**
+     * Get the number of fields in a hash.
+     *
+     * @see https://redis.io/commands/hlen
+     *
+     * @param string $key The hash to check.
+     *
+     * @return Redis|int|false The number of fields or false if the key didn't exist.
+     */
     public function hLen(string $key): Redis|int|false;
 
-    public function hMget(string $key, array $keys): Redis|array|false;
+    /**
+     * Get one or more fields from a hash.
+     *
+     * @see https://redis.io/commands/hmget
+     *
+     * @param string $key    The hash to query.
+     * @param array  $fields One or more fields to query in the hash.
+     *
+     * @return Redis|array|false The fields and values or false if the key didn't exist.
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->del('player:1');
+     *
+     * $redis->hmset('player:1', ['name' => 'Alice', 'age' => '26', 'score' => '1337']);
+     *
+     * // array(2) {
+     * //   ["name"]=>
+     * //   string(5) "Alice"
+     * //   ["score"]=>
+     * //   string(4) "1337"
+     * // }
+     * $redis->hmget('player:1', ['name', 'score']);
+     * ?>
+     * </code>
+     */
+    public function hMget(string $key, array $fields): Redis|array|false;
 
-    public function hMset(string $key, array $keyvals): Redis|bool;
+    /**
+     * Add or update one or more hash fields and values
+     *
+     * @see https://redis.io/commands/hmset
+     *
+     * @param string $key        The hash to create/update
+     * @param array  $fieldvals  An associative array with fields and their values.
+     *
+     * @return Redis|bool True if the operation was successful
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->hmset('updates', ['status' => 'starting', 'elapsed' => 0]);
+     * ?>
+     * </code>
+     */
+    public function hMset(string $key, array $fieldvals): Redis|bool;
 
+    /**
+     * Get one or more random field from a hash.
+     *
+     * @see https://redis.io/commands/hrandfield
+     *
+     * @param string $key     The hash to query.
+     * @param array  $options An array of options to modify how the command behaves.
+     *
+     *                        <code>
+     *                        $options = [
+     *                            'COUNT'      => int  // An optional number of fields to return.
+     *                            'WITHVALUES' => bool // Also return the field values.
+     *                        ];
+     *                        </code>
+     *
+     * @return Redis|array|string One or more random fields (and possibly values).
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->del('settings');
+     *
+     * $redis->hmset('settings', ['path' => '/', 'state' => 'active', 'jobs' => 15]);
+     *
+     * $redis->hrandfield('settings');
+     *
+     * $redis->hrandfield('settings', ['count' => 2, 'withvalues' => true]);
+     * ?>
+     * </code>
+     */
     public function hRandField(string $key, array $options = null): Redis|string|array;
 
     public function hSet(string $key, string $member, mixed $value): Redis|int|false;
 
-    public function hSetNx(string $key, string $member, string $value): Redis|bool;
+    /**
+     * Set a hash field and value, but only if that field does not exist
+     *
+     * @see https://redis.io/commands/hsetnx
+     *
+     * @param string $key   The hash to update.
+     * @param string $field The value to set.
+     *
+     * @return Redis|bool True if the field was set and false if not.
+     *
+     * <code>
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->del('player:1');
+     *
+     * $redis->hmset('player:1', ['name' => 'bob', 'score' => 0]);
+     *
+     * // bool(true)
+     * var_dump($redis->hsetnx('player:1', 'lock', 'enabled'));
+     *
+     * // bool(false)
+     * var_dump($redis->hsetnx('player:1', 'lock', 'enabled'));
+     * </code>
+     */
+    public function hSetNx(string $key, string $field, string $value): Redis|bool;
 
-    public function hStrLen(string $key, string $member): Redis|int|false;
+    /**
+     * Get the string length of a hash field
+     *
+     * @see https://redis.io/commands/hstrlen
+     *
+     * @param string $key   The hash to query.
+     * @param string $field The field to query.
+     *
+     * @return Redis|int|false The string length of the field or false.
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->del('hash');
+     * $redis->hmset('hash', ['50bytes' => str_repeat('a', 50)]);
+     *
+     * // int(50)
+     * $redis->hstrlen('hash', '50bytes');
+     *
+     * </code>
+     */
+    public function hStrLen(string $key, string $field): Redis|int|false;
 
+    /**
+     * Get all of the values from a hash.
+     *
+     * @see https://redis.io/commands/hvals
+     *
+     * @param string $key The hash to query.
+     *
+     * @return Redis|array|false The values from the hash.
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->del('player');
+     *
+     * $redis->hmset('player', ['name' => 'Alice', 'score' => 1337]);
+     *
+     * // array(2) {
+     * //   ["name"]=>
+     * //   string(5) "Alice"
+     * //   ["score"]=>
+     * //   string(4) "1337"
+     * // }
+     * $redis->hgetall('player');
+     * ?>
+     * </code>
+     */
     public function hVals(string $key): Redis|array|false;
 
-    public function hscan(string $key, ?int &$iterator, ?string $pattern = null, int $count = 0): Redis|bool|array;
+
+    /**
+     * Iterate over the fields and values of a hash in an incremental fashion.
+     *
+     * @see https://redis.io/commands/hscan
+     * @see https://redis.io/commands/scan
+     *
+     * @param string $key       The hash to query.
+     * @param int    $iterator  The scan iterator, which should be initialized to NULL before the first call.
+     *                          This value will be updated after every call to hscan, until it reaches zero
+     *                          meaning the scan is complete.
+     * @param string $pattern   An optional glob-style pattern to filter fields with.
+     * @param int    $count     An optional hint to Redis about how many fields and values to return per HSCAN.
+     *
+     * @return Redis|array|bool An array with a subset of fields and values.
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->del('big-hash');
+     *
+     * for ($i = 0; $i < 1000; $i++) {
+     *     $fields["field:$i"] = "value:$i";
+     * }
+     *
+     * $redis->hmset('big-hash', $fields);
+     *
+     * $it = NULL;
+     *
+     * do {
+     *     // Scan the hash but limit it to fields that match '*:1?3'
+     *     $fields = $redis->hscan('big-hash', $it, '*:1?3');
+     *
+     *     foreach ($fields as $field => $value) {
+     *         echo "[$field] => $value\n";
+     *     }
+     * } while ($it != 0);
+     *
+     * // --- OUTPUT ---
+     * // [field:143] => value:143
+     * // [field:133] => value:133
+     * // [field:163] => value:163
+     * // [field:183] => value:183
+     * // [field:153] => value:153
+     * // [field:113] => value:113
+     * // [field:103] => value:103
+     * // [field:193] => value:193
+     * // [field:123] => value:123
+     * // [field:173] => value:173
+     * ?>
+     * </code>
+     */
+    public function hscan(string $key, ?int &$iterator, ?string $pattern = null, int $count = 0): Redis|array|bool;
 
     /**
      * Increment a key's value, optionally by a specifc amount.
diff --git a/redis_arginfo.h b/redis_arginfo.h
index df218e35..d11cd333 100644
--- a/redis_arginfo.h
+++ b/redis_arginfo.h
@@ -1,5 +1,5 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: 35a49b804f7cb67b7cd0a9a1094125855addaf1e */
+ * Stub hash: c95a6704d3c51686748694926d6f4b0f55a2f3df */
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis___construct, 0, 0, 0)
 	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, options, IS_ARRAY, 0, "null")
@@ -386,13 +386,13 @@ ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_hIncrBy, 0, 3, Redis, MAY_BE_LONG|MAY_BE_FALSE)
 	ZEND_ARG_TYPE_INFO(0, key, IS_STRING, 0)
-	ZEND_ARG_TYPE_INFO(0, member, IS_STRING, 0)
+	ZEND_ARG_TYPE_INFO(0, field, IS_STRING, 0)
 	ZEND_ARG_TYPE_INFO(0, value, IS_LONG, 0)
 ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_hIncrByFloat, 0, 3, Redis, MAY_BE_DOUBLE|MAY_BE_FALSE)
 	ZEND_ARG_TYPE_INFO(0, key, IS_STRING, 0)
-	ZEND_ARG_TYPE_INFO(0, member, IS_STRING, 0)
+	ZEND_ARG_TYPE_INFO(0, field, IS_STRING, 0)
 	ZEND_ARG_TYPE_INFO(0, value, IS_DOUBLE, 0)
 ZEND_END_ARG_INFO()
 
@@ -402,12 +402,12 @@ ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_hMget, 0, 2, Redis, MAY_BE_ARRAY|MAY_BE_FALSE)
 	ZEND_ARG_TYPE_INFO(0, key, IS_STRING, 0)
-	ZEND_ARG_TYPE_INFO(0, keys, IS_ARRAY, 0)
+	ZEND_ARG_TYPE_INFO(0, fields, IS_ARRAY, 0)
 ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_hMset, 0, 2, Redis, MAY_BE_BOOL)
 	ZEND_ARG_TYPE_INFO(0, key, IS_STRING, 0)
-	ZEND_ARG_TYPE_INFO(0, keyvals, IS_ARRAY, 0)
+	ZEND_ARG_TYPE_INFO(0, fieldvals, IS_ARRAY, 0)
 ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_hRandField, 0, 1, Redis, MAY_BE_STRING|MAY_BE_ARRAY)
@@ -423,18 +423,18 @@ ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_hSetNx, 0, 3, Redis, MAY_BE_BOOL)
 	ZEND_ARG_TYPE_INFO(0, key, IS_STRING, 0)
-	ZEND_ARG_TYPE_INFO(0, member, IS_STRING, 0)
+	ZEND_ARG_TYPE_INFO(0, field, IS_STRING, 0)
 	ZEND_ARG_TYPE_INFO(0, value, IS_STRING, 0)
 ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_hStrLen, 0, 2, Redis, MAY_BE_LONG|MAY_BE_FALSE)
 	ZEND_ARG_TYPE_INFO(0, key, IS_STRING, 0)
-	ZEND_ARG_TYPE_INFO(0, member, IS_STRING, 0)
+	ZEND_ARG_TYPE_INFO(0, field, IS_STRING, 0)
 ZEND_END_ARG_INFO()
 
 #define arginfo_class_Redis_hVals arginfo_class_Redis_hGetAll
 
-ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_hscan, 0, 2, Redis, MAY_BE_BOOL|MAY_BE_ARRAY)
+ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_hscan, 0, 2, Redis, MAY_BE_ARRAY|MAY_BE_BOOL)
 	ZEND_ARG_TYPE_INFO(0, key, IS_STRING, 0)
 	ZEND_ARG_TYPE_INFO(1, iterator, IS_LONG, 1)
 	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, pattern, IS_STRING, 1, "null")
diff --git a/redis_legacy_arginfo.h b/redis_legacy_arginfo.h
index 4240ca1c..cde9a871 100644
--- a/redis_legacy_arginfo.h
+++ b/redis_legacy_arginfo.h
@@ -1,5 +1,5 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: 35a49b804f7cb67b7cd0a9a1094125855addaf1e */
+ * Stub hash: c95a6704d3c51686748694926d6f4b0f55a2f3df */
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis___construct, 0, 0, 0)
 	ZEND_ARG_INFO(0, options)
@@ -352,7 +352,7 @@ ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_hIncrBy, 0, 0, 3)
 	ZEND_ARG_INFO(0, key)
-	ZEND_ARG_INFO(0, member)
+	ZEND_ARG_INFO(0, field)
 	ZEND_ARG_INFO(0, value)
 ZEND_END_ARG_INFO()
 
@@ -364,21 +364,25 @@ ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_hMget, 0, 0, 2)
 	ZEND_ARG_INFO(0, key)
-	ZEND_ARG_INFO(0, keys)
+	ZEND_ARG_INFO(0, fields)
 ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_hMset, 0, 0, 2)
 	ZEND_ARG_INFO(0, key)
-	ZEND_ARG_INFO(0, keyvals)
+	ZEND_ARG_INFO(0, fieldvals)
 ZEND_END_ARG_INFO()
 
 #define arginfo_class_Redis_hRandField arginfo_class_Redis_getEx
 
-#define arginfo_class_Redis_hSet arginfo_class_Redis_hIncrBy
+ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_hSet, 0, 0, 3)
+	ZEND_ARG_INFO(0, key)
+	ZEND_ARG_INFO(0, member)
+	ZEND_ARG_INFO(0, value)
+ZEND_END_ARG_INFO()
 
 #define arginfo_class_Redis_hSetNx arginfo_class_Redis_hIncrBy
 
-#define arginfo_class_Redis_hStrLen arginfo_class_Redis_hGet
+#define arginfo_class_Redis_hStrLen arginfo_class_Redis_hExists
 
 #define arginfo_class_Redis_hVals arginfo_class_Redis__prefix
 
diff --git a/tests/RedisTest.php b/tests/RedisTest.php
index a88d8009..606c4e73 100644
--- a/tests/RedisTest.php
+++ b/tests/RedisTest.php
@@ -931,7 +931,7 @@ class Redis_Test extends TestSuite
 
         /* Test passing an array as well as the keys variadic */
         $this->assertEquals(count($mkeys), $this->redis->exists($mkeys));
-        $this->assertEquals(count($mkeys), call_user_func_array([$this->redis, 'exists'], $mkeys));
+        $this->assertEquals(count($mkeys), $this->redis->exists(...$mkeys));
     }
 
     public function testTouch() {