Documentation: More docblocks and examples

[skip ci]

6 files changed, 158 insertions, 13 deletions

diff --git a/redis.stub.php b/redis.stub.php
index 51aff493..f8a87a82 100644
--- a/redis.stub.php
+++ b/redis.stub.php
@@ -40,7 +40,7 @@ class Redis {
      *     'retryInterval'  => 100,
      *
      *      // Which backoff algorithm to use.  'decorrelated jitter' is
-     *      // likely the best one for most solutiona, but there are many
+     *      // likely the best one for most solution, but there are many
      *      // to choose from:
      *      //     REDIS_BACKOFF_ALGORITHM_DEFAULT
      *      //     REDIS_BACKOFF_ALGORITHM_CONSTANT
@@ -143,7 +143,7 @@ class Redis {
      * as set with Redis::setOption().
      *
      * @param  string $value  The value which has been serialized and compressed.
-     * @return mixed          The uncompressed and deserialized value.
+     * @return mixed          The uncompressed and eserialized value.
      *
      */
     public function _unpack(string $value): mixed;
@@ -294,6 +294,7 @@ class Redis {
      * Following are examples of the two main ways to call this method.
      *
      * <code>
+     * <?php
      * // Method 1 - Variadic, with the last argument being our timeout
      * $redis->bzPopMax('key1', 'key2', 'key3', 1.5);
      *
@@ -1187,14 +1188,114 @@ class Redis {
      */
     public function sUnionStore(string $dst, string $key, string ...$other_keys): Redis|int|false;
 
-    public function save(): bool;
+    /**
+     * Persist the Redis database to disk.  This command will block the server until the save is
+     * completed.  For a nonblocking alternative, see Redis::bgsave().
+     *
+     * @see https://redis.io/commands/save
+     * @see Redis::bgsave()
+     *
+     * @return Redis|bool Returns true unless an error occurs.
+     */
+    public function save(): Redis|bool;
 
+    /**
+     * Incrementally scan the Redis keyspace, with optional pattern and type matching.
+     *
+     * @see https://redis.io/commands/scan
+     * @see Redis::setOption()
+     *
+     * @param int    $iterator The cursor returned by Redis for every subsequent call to SCAN.  On
+     *                         the initial invocation of the call, it should be initialized by the
+     *                         caller to NULL.  Each time SCAN is invoked, the iterator will be
+     *                         updated to a new number, until finally Redis will set the value to
+     *                         zero, indicating that the scan is complete.
+     *
+     * @param string $pattern  An optional glob-style pattern for matching key names.  If passed as
+     *                         NULL, it is the equivalent of sending '*' (match every key).
+     *
+     * @param int    $count    A hint to redis that tells it how many keys to return in a single
+     *                         call to SCAN.  The larger the number, the longer Redis may block
+     *                         clients while iterating the key space.
+     *
+     * @param string $type     An optional argument to specify which key types to scan (e.g.
+     *                         'STRING', 'LIST', 'SET')
+     *
+     * @return array|false     An array of keys, or false if no keys were returned for this
+     *                         invocation of scan.  Note that it is possible for Redis to return
+     *                         zero keys before having scanned the entire key space, so the caller
+     *                         should instead continue to SCAN until the iterator reference is
+     *                         returned to zero.
+     *
+     * A note about Redis::SCAN_NORETRY and Redis::SCAN_RETRY.
+     *
+     * For convenience, PhpRedis can retry SCAN commands itself when Redis returns an empty array of
+     * keys with a nonzero iterator.  This can happen when matching against a pattern that very few
+     * keys match inside a key space with a great many keys.  The following example demonstrates how
+     * to use Redis::scan() with the option disabled and enabled.
+     *
+     * <code>
+     * <?php
+     *
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->setOption(Redis::OPT_SCAN, Redis::SCAN_NORETRY);
+     *
+     * $it = NULL;
+     *
+     * do {
+     *     $keys = $redis->scan($it, '*zorg*');
+     *     foreach ($keys as $key) {
+     *         echo "KEY: $key\n";
+     *     }
+     * } while ($it != 0);
+     *
+     * $redis->setOption(Redis::OPT_SCAN, Redis::SCAN_RETRY);
+     *
+     * $it = NULL;
+     *
+     * // When Redis::SCAN_RETRY is enabled, we can use simpler logic, as we will never receive an
+     * // empty array of keys when the iterator is nonzero.
+     * while ($keys = $redis->scan($it, '*zorg*')) {
+     *     foreach ($keys as $key) {
+     *         echo "KEY: $key\n";
+     *     }
+     * }
+     * ?>
+     * </code>
+     */
     public function scan(?int &$iterator, ?string $pattern = null, int $count = 0, string $type = NULL): array|false;
 
     public function scard(string $key): Redis|int|false;
 
     public function script(string $command, mixed ...$args): mixed;
 
+    /**
+     * Select a specific Redis database.
+     *
+     * @param int $db The database to select.  Note that by default Redis has 16 databases (0-15).
+     *
+     * @return Redis|bool true on success and false on failure
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->select(1);
+     * $redis->set('this_is_db_1', 'test');
+     *
+     * $redis->select(0);
+     * var_dump($redis->exists('this_is_db_1'));
+     *
+     * $redis->select(1);
+     * var_dump($redis->exists('this_is_db_1'));
+     *
+     * // --- OUTPUT ---
+     * // int(0)
+     * // int(1)
+     * ?>
+     * </code>
+     */
     public function select(int $db): Redis|bool;
 
     public function set(string $key, mixed $value, mixed $opt = NULL): Redis|string|bool;
@@ -1217,6 +1318,21 @@ class Redis {
      *
      *  OPT_SCAN                   enum     Redis::OPT_SCAN_RETRY, or Redis::OPT_SCAN_NORETRY
      *
+     *                                      Redis::SCAN_NORETRY (default)
+     *                                      --------------------------------------------------------
+     *                                      PhpRedis will only call `SCAN` once for every time the
+     *                                      user calls Redis::scan().  This means it is possible for
+     *                                      an empty array of keys to be returned while there are
+     *                                      still more keys to be processed.
+     *
+     *                                      Redis::SCAN_RETRY
+     *                                      --------------------------------------------------------
+     *                                      PhpRedis may make multiple calls to `SCAN` for every
+     *                                      time the user calls Redis::scan(), and will never return
+     *                                      an empty array of keys unless Redis returns the iterator
+     *                                      to zero (meaning the `SCAN` is complete).
+     *
+     *
      *  OPT_SERIALIZER             int      One of the installed serializers, which can vary depending
      *                                      on how PhpRedis was compiled.  All of the supported serializers
      *                                      are as follows:
@@ -1303,8 +1419,8 @@ class Redis {
      *
      * @param string $operation  The operation you wish to perform.  This can
      *                           be one of the following values:
-     *                           'GET'   - Retreive the Redis slowlog as an array.
-     *                           'LEN'   - Retreive the length of the slowlog.
+     *                           'GET'   - Retrieve the Redis slowlog as an array.
+     *                           'LEN'   - Retrieve the length of the slowlog.
      *                           'RESET' - Remove all slowlog entries.
      * <code>
      * <?php
@@ -1315,7 +1431,7 @@ class Redis {
      * </code>
      *
      * @param int    $length     This optional argument can be passed when operation
-     *                           is 'get' and will specify how many elements to retreive.
+     *                           is 'get' and will specify how many elements to retrieve.
      *                           If omitted Redis will send up to a default number of
      *                           entries, which is configurable.
      *
@@ -1385,6 +1501,32 @@ class Redis {
      */
     public function sortDescAlpha(string $key, ?string $pattern = null, mixed $get = null, int $offset = -1, int $count = -1, ?string $store = null): array;
 
+    /**
+     * Remove one or more values from a Redis SET key.
+     *
+     * @see https://redis.io/commands/srem
+     *
+     * @param string $key         The Redis SET key in question.
+     * @param mixed  $value       The first value to remove.
+     * @param mixed  $more_values One or more additional values to remove.
+     *
+     * @return Redis|int|false    The number of values removed from the set or false on failure.
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->pipeline()->del('set1')
+     *                   ->sadd('set1', 'foo', 'bar', 'baz')
+     *                   ->exec();
+     *
+     * var_dump($redis->sRem('set1', 'foo', 'bar', 'not-in-the-set'));
+     *
+     * // --- OUTPUT ---
+     * // int(2)
+     * ?>
+     * </code>
+     */
     public function srem(string $key, mixed $value, mixed ...$other_values): Redis|int|false;
 
     public function sscan(string $key, ?int &$iterator, ?string $pattern = null, int $count = 0): array|false;
@@ -1502,7 +1644,7 @@ class Redis {
     public function zPopMin(string $key, int $value = null): Redis|array|false;
 
     /**
-     * Retreive a range of elements of a sorted set between a start and end point.
+     * Retrieve a range of elements of a sorted set between a start and end point.
      * How the command works in particular is greatly affected by the options that
      * are passed in.
      *
@@ -1556,7 +1698,7 @@ class Redis {
      * @param string           $end     The ending index to store
      * @param array|bool|null  $options Our options array that controls how the command will function.
      *
-     * @return Redis|int|false The number of elements stored in dstkey or false on failure.
+     * @return Redis|int|false The number of elements stored in $dstkey or false on failure.
      *
      * See Redis::zRange for a full description of the possible options.
      */
diff --git a/redis_arginfo.h b/redis_arginfo.h
index 39085674..4d0a341f 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: 8e423eab8d5b732655e7fcaab4d0800aadc38747 */
+ * Stub hash: ed7bf573247cb4bd4ead254d75ad5b60a97313be */
 
 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")
@@ -739,7 +739,7 @@ ZEND_END_ARG_INFO()
 
 #define arginfo_class_Redis_sUnionStore arginfo_class_Redis_sDiffStore
 
-#define arginfo_class_Redis_save arginfo_class_Redis_clearLastError
+#define arginfo_class_Redis_save arginfo_class_Redis_bgSave
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_MASK_EX(arginfo_class_Redis_scan, 0, 1, MAY_BE_ARRAY|MAY_BE_FALSE)
 	ZEND_ARG_TYPE_INFO(1, iterator, IS_LONG, 1)
diff --git a/redis_cluster.stub.php b/redis_cluster.stub.php
index 35e72cf6..e5fb7e88 100644
--- a/redis_cluster.stub.php
+++ b/redis_cluster.stub.php
@@ -441,6 +441,9 @@ class RedisCluster {
 
     public function srandmember(string $key, int $count = 0): RedisCluster|string|array|false;
 
+    /**
+     * @see Redis::srem
+     */
     public function srem(string $key, mixed $value, mixed ...$other_values): RedisCluster|int|false;
 
     public function sscan(string $key, ?int &$iterator, ?string $pattern = null, int $count = 0): array|false;
diff --git a/redis_cluster_arginfo.h b/redis_cluster_arginfo.h
index f5fb6bab..b8174f47 100644
--- a/redis_cluster_arginfo.h
+++ b/redis_cluster_arginfo.h
@@ -1,5 +1,5 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: 836411b2d661943a61fd5a2aadac30997a506cde */
+ * Stub hash: 37a25fa4537a2d10a2c2a8b09292e77e5cc35d59 */
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_RedisCluster___construct, 0, 0, 1)
 	ZEND_ARG_TYPE_INFO(0, name, IS_STRING, 1)
diff --git a/redis_cluster_legacy_arginfo.h b/redis_cluster_legacy_arginfo.h
index feec4298..8a82598a 100644
--- a/redis_cluster_legacy_arginfo.h
+++ b/redis_cluster_legacy_arginfo.h
@@ -1,5 +1,5 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: 836411b2d661943a61fd5a2aadac30997a506cde */
+ * Stub hash: 37a25fa4537a2d10a2c2a8b09292e77e5cc35d59 */
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_RedisCluster___construct, 0, 0, 1)
 	ZEND_ARG_INFO(0, name)
diff --git a/redis_legacy_arginfo.h b/redis_legacy_arginfo.h
index 145984d8..d6f5641a 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: 8e423eab8d5b732655e7fcaab4d0800aadc38747 */
+ * Stub hash: ed7bf573247cb4bd4ead254d75ad5b60a97313be */
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis___construct, 0, 0, 0)
 	ZEND_ARG_INFO(0, options)