From 450904f75c2e4d45f29813bb73d01c6a0ff61ddb Mon Sep 17 00:00:00 2001 From: michael-grunder Date: Mon, 7 Nov 2022 17:45:08 -0800 Subject: Documentation: More docblocks with examples. --- redis.stub.php | 306 +++++++++++++++++++++++++++++++++++++++++++++++-- redis_arginfo.h | 16 +-- redis_legacy_arginfo.h | 16 ++- tests/RedisTest.php | 2 +- 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. + * + * + * '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); + * ?> + * + * + */ + 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. + * + * + * $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); + * ?> + * + */ + 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. + * + * + * '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'); + * ?> + * + */ 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. + * + * + * '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']); + * ?> + * + */ + 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 + * + * + * 'localhost']); + * + * $redis->hmset('updates', ['status' => 'starting', 'elapsed' => 0]); + * ?> + * + */ + 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. + * + * + * $options = [ + * 'COUNT' => int // An optional number of fields to return. + * 'WITHVALUES' => bool // Also return the field values. + * ]; + * + * + * @return Redis|array|string One or more random fields (and possibly values). + * + * + * 'localhost']); + * + * $redis->del('settings'); + * + * $redis->hmset('settings', ['path' => '/', 'state' => 'active', 'jobs' => 15]); + * + * $redis->hrandfield('settings'); + * + * $redis->hrandfield('settings', ['count' => 2, 'withvalues' => true]); + * ?> + * + */ 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. + * + * + * $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')); + * + */ + 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. + * + * + * 'localhost']); + * + * $redis->del('hash'); + * $redis->hmset('hash', ['50bytes' => str_repeat('a', 50)]); + * + * // int(50) + * $redis->hstrlen('hash', '50bytes'); + * + * + */ + 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. + * + * + * 'localhost']); + * + * $redis->del('player'); + * + * $redis->hmset('player', ['name' => 'Alice', 'score' => 1337]); + * + * // array(2) { + * // ["name"]=> + * // string(5) "Alice" + * // ["score"]=> + * // string(4) "1337" + * // } + * $redis->hgetall('player'); + * ?> + * + */ 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. + * + * + * '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 + * ?> + * + */ + 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() { -- cgit v1.2.3