More docblocks and refactor SLAVEOF command.

Add additional complete docblocks for a few more commands.

Refactor SLAVEOF handler to conform with more modern PhpRedis command
handlers.

Create REPLICAOF and deprecate SLAVEOF as Redis has done since 5.0.0.

6 files changed, 143 insertions, 39 deletions

diff --git a/redis.c b/redis.c
index b305075f..0afb4b48 100644
--- a/redis.c
+++ b/redis.c
@@ -2559,41 +2559,18 @@ PHP_METHOD(Redis, bgrewriteaof)
 }
 /* }}} */
 
-/* {{{ proto string Redis::slaveof([host, port]) */
-PHP_METHOD(Redis, slaveof)
-{
-    zval *object;
-    RedisSock *redis_sock;
-    char *cmd = "", *host = NULL;
-    size_t host_len;
-    zend_long port = 6379;
-    int cmd_len;
-
-    if (zend_parse_method_parameters(ZEND_NUM_ARGS(), getThis(),
-                                     "O|sl", &object, redis_ce, &host,
-                                     &host_len, &port) == FAILURE)
-    {
-        RETURN_FALSE;
-    }
-    if (port < 0 || (redis_sock = redis_sock_get(object, 0)) == NULL) {
-        RETURN_FALSE;
-    }
-
-    if (host && host_len) {
-        cmd_len = REDIS_SPPRINTF(&cmd, "SLAVEOF", "sd", host, host_len, (int)port);
-    } else {
-        cmd_len = REDIS_SPPRINTF(&cmd, "SLAVEOF", "ss", "NO", 2, "ONE", 3);
-    }
-
-    REDIS_PROCESS_REQUEST(redis_sock, cmd, cmd_len);
-    if (IS_ATOMIC(redis_sock)) {
-      redis_boolean_response(INTERNAL_FUNCTION_PARAM_PASSTHRU, redis_sock,
-          NULL, NULL);
-    }
-    REDIS_PROCESS_RESPONSE(redis_boolean_response);
+/* {{{ public function slaveof(string $host = NULL, int $port = NULL): Redis|bool }}} */
+PHP_METHOD(Redis, slaveof) {
+    REDIS_PROCESS_KW_CMD("SLAVEOF", redis_replicaof_cmd, redis_boolean_response);
 }
 /* }}} */
 
+/* {{{ public function replicaof(string $host = NULL, int $port = NULL): Redis|bool }}} */
+PHP_METHOD(Redis, replicaof) {
+    REDIS_PROCESS_KW_CMD("REPLICAOF", redis_replicaof_cmd, redis_boolean_response);
+}
+
+/* }}} */
 /* {{{ proto string Redis::object(key) */
 PHP_METHOD(Redis, object)
 {
diff --git a/redis.stub.php b/redis.stub.php
index 64faa3bc..d2ed4449 100644
--- a/redis.stub.php
+++ b/redis.stub.php
@@ -1751,14 +1751,102 @@ class Redis {
     public function setOption(int $option, mixed $value): bool;
 
     /** @return bool|Redis */
+
+    /**
+     * Set a Redis STRING key with a specific expiration in seconds.
+     *
+     * @param string $key     The name of the key to set.
+     * @param int    $expire  The key's expiration in seconds.
+     * @param mixed  $value   The value to set the key.
+     *
+     * @return Redis|bool True on success or false on failure.
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * // Set a key with a 60 second expiration
+     * $redis->set('some_key', 60, 'some_value');
+     *
+     * ?>php
+     * </code>
+     */
     public function setex(string $key, int $expire, mixed $value);
 
     /** @return bool|array|Redis */
     public function setnx(string $key, mixed $value);
 
+    /**
+     * Check whether a given value is the member of a Redis SET.
+     *
+     * @param string $key   The redis set to check.
+     * @param mixed  $value The value to test.
+     *
+     * @return Redis|bool True if the member exists and false if not.
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->multi()
+     *       ->del('myset')
+     *       ->sadd('myset', 'foo', 'bar', 'baz')
+     *       ->exec();
+     *
+     * // Will return true, as 'foo' is in the set
+     * $redis->sismember('myset', 'foo');
+     *
+     * // Will return false, as 'not-in-set' is not in the set
+     * $redis->sismember('myset', 'not-in-set');
+     * ?>
+     * </code>
+     */
     public function sismember(string $key, mixed $value): Redis|bool;
 
-    public function slaveof(string $host = null, int $port = 6379): bool;
+    /**
+     * Turn a redis instance into a replica of another or promote a replica
+     * to a primary.
+     *
+     * This method and the corresponding command in Redis has been marked deprecated
+     * and users should instead use Redis::replicaof() if connecting to redis-server
+     * >= 5.0.0.
+     *
+     * @deprecated
+     *
+     * @see https://redis.io/commands/slaveof
+     * @see https://redis.io/commands/replicaof
+     * @see Redis::slaveof()
+     */
+    public function slaveof(string $host = NULL, int $port = 6379): Redis|bool;
+
+    /**
+     * Used to turn a Redis instance into a replica of another, or to remove
+     * replica status promoting the instance to a primary.
+     *
+     * @see https://redis.io/commands/replicaof
+     * @see https://redis.io/commands/slaveof
+     * @see Redis::slaveof()
+     *
+     * @param string $host The host of the primary to start replicating.
+     * @param string $port The port of the primary to start replicating.
+     *
+     * @return Redis|bool Success if we were successfully able to start replicating a primary or
+     *                    were able to promote teh replicat to a primary.
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * // Attempt to become a replica of a Redis instance at 127.0.0.1:9999
+     * $redis->slaveof('127.0.0.1', 9999);
+     *
+     * // When passed no arguments, PhpRedis will deliver the command `SLAVEOF NO ONE`
+     * // attempting to promote the instance to a primary.
+     * $redis->slaveof();
+     * ?>
+     * </code>
+     */
+    public function replicaof(string $host = NULL, int $port = 6379): Redis|bool;
 
     /**
      * Update one or more keys last modified metadata.
diff --git a/redis_arginfo.h b/redis_arginfo.h
index 5833affe..eabfc658 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: 5554480fcf6749dcfd69f371ad8dbd07fd8ed4c4 */
+ * Stub hash: 8c51e9b0082cb7939c7bc8dc226132eede02f420 */
 
 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")
@@ -788,11 +788,13 @@ ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_sismember, 0, 2,
 	ZEND_ARG_TYPE_INFO(0, value, IS_MIXED, 0)
 ZEND_END_ARG_INFO()
 
-ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_class_Redis_slaveof, 0, 0, _IS_BOOL, 0)
-	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, host, IS_STRING, 0, "null")
+ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_slaveof, 0, 0, Redis, MAY_BE_BOOL)
+	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, host, IS_STRING, 0, "NULL")
 	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, port, IS_LONG, 0, "6379")
 ZEND_END_ARG_INFO()
 
+#define arginfo_class_Redis_replicaof arginfo_class_Redis_slaveof
+
 ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_touch, 0, 1, Redis, MAY_BE_LONG|MAY_BE_FALSE)
 	ZEND_ARG_TYPE_MASK(0, key_or_array, MAY_BE_ARRAY|MAY_BE_STRING, NULL)
 	ZEND_ARG_VARIADIC_TYPE_INFO(0, more_keys, IS_STRING, 0)
@@ -1291,6 +1293,7 @@ ZEND_METHOD(Redis, setex);
 ZEND_METHOD(Redis, setnx);
 ZEND_METHOD(Redis, sismember);
 ZEND_METHOD(Redis, slaveof);
+ZEND_METHOD(Redis, replicaof);
 ZEND_METHOD(Redis, touch);
 ZEND_METHOD(Redis, slowlog);
 ZEND_METHOD(Redis, sort);
@@ -1539,7 +1542,8 @@ static const zend_function_entry class_Redis_methods[] = {
 	ZEND_ME(Redis, setex, arginfo_class_Redis_setex, ZEND_ACC_PUBLIC)
 	ZEND_ME(Redis, setnx, arginfo_class_Redis_setnx, ZEND_ACC_PUBLIC)
 	ZEND_ME(Redis, sismember, arginfo_class_Redis_sismember, ZEND_ACC_PUBLIC)
-	ZEND_ME(Redis, slaveof, arginfo_class_Redis_slaveof, ZEND_ACC_PUBLIC)
+	ZEND_ME(Redis, slaveof, arginfo_class_Redis_slaveof, ZEND_ACC_PUBLIC|ZEND_ACC_DEPRECATED)
+	ZEND_ME(Redis, replicaof, arginfo_class_Redis_replicaof, ZEND_ACC_PUBLIC)
 	ZEND_ME(Redis, touch, arginfo_class_Redis_touch, ZEND_ACC_PUBLIC)
 	ZEND_ME(Redis, slowlog, arginfo_class_Redis_slowlog, ZEND_ACC_PUBLIC)
 	ZEND_ME(Redis, sort, arginfo_class_Redis_sort, ZEND_ACC_PUBLIC)
diff --git a/redis_commands.c b/redis_commands.c
index dabeae3f..187a2cdf 100644
--- a/redis_commands.c
+++ b/redis_commands.c
@@ -1126,6 +1126,33 @@ int redis_intercard_cmd(INTERNAL_FUNCTION_PARAMETERS, RedisSock *redis_sock,
     return SUCCESS;
 }
 
+int redis_replicaof_cmd(INTERNAL_FUNCTION_PARAMETERS, RedisSock *redis_sock,
+                        char *kw, char **cmd, int *cmd_len, short *slot,
+                        void **ctx)
+{
+    zend_string *host = NULL;
+    zend_long port = 6379;
+
+    ZEND_PARSE_PARAMETERS_START(0, 2)
+        Z_PARAM_OPTIONAL
+        Z_PARAM_STR(host)
+        Z_PARAM_LONG(port)
+    ZEND_PARSE_PARAMETERS_END_EX(return FAILURE);
+
+    if (port < 0 || port > UINT16_MAX) {
+        php_error_docref(NULL, E_WARNING, "Invalid port %ld", (long)port);
+        return FAILURE;
+    }
+
+    if (ZEND_NUM_ARGS() == 2) {
+        *cmd_len = REDIS_SPPRINTF(cmd, kw, "Sd", host, (int)port);
+    } else {
+        *cmd_len = REDIS_SPPRINTF(cmd, kw, "ss", ZEND_STRL("NO"), ZEND_STRL("ONE"));
+    }
+
+    return SUCCESS;
+}
+
 int
 redis_zinterunion_cmd(INTERNAL_FUNCTION_PARAMETERS, RedisSock *redis_sock,
                       char *kw, char **cmd, int *cmd_len, short *slot,
diff --git a/redis_commands.h b/redis_commands.h
index 47176c48..f56662e7 100644
--- a/redis_commands.h
+++ b/redis_commands.h
@@ -37,6 +37,10 @@ char *redis_variadic_str_cmd(char *kw, zval *argv, int argc, int *cmd_len);
  * we can write one function to handle all of them.  For example, there are
  * many COMMAND key value commands, or COMMAND key commands. */
 
+int redis_replicaof_cmd(INTERNAL_FUNCTION_PARAMETERS, RedisSock *redis_sock,
+                        char *kw, char **cmd, int *cmd_len, short *slot,
+                        void **ctx);
+
 int redis_empty_cmd(INTERNAL_FUNCTION_PARAMETERS, RedisSock *redis_sock,
     char *kw, char **cmd, int *cmd_len, short *slot, void **ctx);
 
diff --git a/redis_legacy_arginfo.h b/redis_legacy_arginfo.h
index 5d4355cb..a793ef44 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: 5554480fcf6749dcfd69f371ad8dbd07fd8ed4c4 */
+ * Stub hash: 8c51e9b0082cb7939c7bc8dc226132eede02f420 */
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis___construct, 0, 0, 0)
 	ZEND_ARG_INFO(0, options)
@@ -673,6 +673,8 @@ ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_slaveof, 0, 0, 0)
 	ZEND_ARG_INFO(0, port)
 ZEND_END_ARG_INFO()
 
+#define arginfo_class_Redis_replicaof arginfo_class_Redis_slaveof
+
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_touch, 0, 0, 1)
 	ZEND_ARG_INFO(0, key_or_array)
 	ZEND_ARG_VARIADIC_INFO(0, more_keys)
@@ -1129,6 +1131,7 @@ ZEND_METHOD(Redis, setex);
 ZEND_METHOD(Redis, setnx);
 ZEND_METHOD(Redis, sismember);
 ZEND_METHOD(Redis, slaveof);
+ZEND_METHOD(Redis, replicaof);
 ZEND_METHOD(Redis, touch);
 ZEND_METHOD(Redis, slowlog);
 ZEND_METHOD(Redis, sort);
@@ -1377,7 +1380,8 @@ static const zend_function_entry class_Redis_methods[] = {
 	ZEND_ME(Redis, setex, arginfo_class_Redis_setex, ZEND_ACC_PUBLIC)
 	ZEND_ME(Redis, setnx, arginfo_class_Redis_setnx, ZEND_ACC_PUBLIC)
 	ZEND_ME(Redis, sismember, arginfo_class_Redis_sismember, ZEND_ACC_PUBLIC)
-	ZEND_ME(Redis, slaveof, arginfo_class_Redis_slaveof, ZEND_ACC_PUBLIC)
+	ZEND_ME(Redis, slaveof, arginfo_class_Redis_slaveof, ZEND_ACC_PUBLIC|ZEND_ACC_DEPRECATED)
+	ZEND_ME(Redis, replicaof, arginfo_class_Redis_replicaof, ZEND_ACC_PUBLIC)
 	ZEND_ME(Redis, touch, arginfo_class_Redis_touch, ZEND_ACC_PUBLIC)
 	ZEND_ME(Redis, slowlog, arginfo_class_Redis_slowlog, ZEND_ACC_PUBLIC)
 	ZEND_ME(Redis, sort, arginfo_class_Redis_sort, ZEND_ACC_PUBLIC)