docs: document RedisSentinel 'hosts' option

- Stub phpdoc on __construct describes the 'hosts' option alongside the existing single-host parameters. - sentinel.md gains a 'Multi-host support' section covering API, semantics (sticky, bounded retry, no rehydration), and error handling (RedisException on validation and exhaustion). - Regenerated arginfo reflects only the new stub hash; method signatures are unchanged. Refs #2819
phpredis · nikamodis · Apr 22, 2026 · Apr 22, 2026 · Apr 22, 2026 · Apr 22, 2026
commit d05e493df1f5476127269c921d9a459b11a1cfe2
diff --git a/redis_sentinel.stub.php b/redis_sentinel.stub.php
@@ -8,6 +8,21 @@
 
 class RedisSentinel {
 
+    /**
+     * @param array|null $options Connection options. Accepts:
+     *   - 'host'            (string, default '127.0.0.1') - single Sentinel host
+     *   - 'port'            (int, default 26379)          - single Sentinel port
+     *   - 'hosts'           (list<array{host:string,port?:int}>) - multiple Sentinel
+     *                       hosts. When provided, 'host' and 'port' are ignored and
+     *                       the client automatically falls back to the next host
+     *                       on network failure. See issue #2819.
+     *   - 'connectTimeout'  (float)
+     *   - 'persistent'      (?string)
+     *   - 'retryInterval'   (int)
+     *   - 'readTimeout'     (float)
+     *   - 'auth'            (string|array)
+     *   - 'ssl'             (array)
+     */
     public function __construct(?array $options = null);
 
 	/** @return bool|RedisSentinel */

diff --git a/redis_sentinel_arginfo.h b/redis_sentinel_arginfo.h
@@ -1,5 +1,5 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: ca40579af888c5bb0661cd0201d840297474479a */
+ * Stub hash: 65a689d40abaa87e77542700a99742b597051699 */
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_RedisSentinel___construct, 0, 0, 0)
 	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, options, IS_ARRAY, 1, "null")
@@ -33,6 +33,7 @@ ZEND_END_ARG_INFO()
 
 #define arginfo_class_RedisSentinel_slaves arginfo_class_RedisSentinel_ckquorum
 
+
 ZEND_METHOD(RedisSentinel, __construct);
 ZEND_METHOD(RedisSentinel, ckquorum);
 ZEND_METHOD(RedisSentinel, failover);
@@ -46,6 +47,7 @@ ZEND_METHOD(RedisSentinel, reset);
 ZEND_METHOD(RedisSentinel, sentinels);
 ZEND_METHOD(RedisSentinel, slaves);
 
+
 static const zend_function_entry class_RedisSentinel_methods[] = {
 	ZEND_ME(RedisSentinel, __construct, arginfo_class_RedisSentinel___construct, ZEND_ACC_PUBLIC)
 	ZEND_ME(RedisSentinel, ckquorum, arginfo_class_RedisSentinel_ckquorum, ZEND_ACC_PUBLIC)
@@ -67,11 +69,7 @@ static zend_class_entry *register_class_RedisSentinel(void)
 	zend_class_entry ce, *class_entry;
 
 	INIT_CLASS_ENTRY(ce, "RedisSentinel", class_RedisSentinel_methods);
-#if (PHP_VERSION_ID >= 80400)
-	class_entry = zend_register_internal_class_with_flags(&ce, NULL, 0);
-#else
 	class_entry = zend_register_internal_class_ex(&ce, NULL);
-#endif
 
 	return class_entry;
 }
diff --git a/redis_sentinel_legacy_arginfo.h b/redis_sentinel_legacy_arginfo.h
@@ -1,5 +1,5 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: ca40579af888c5bb0661cd0201d840297474479a */
+ * Stub hash: 65a689d40abaa87e77542700a99742b597051699 */
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_RedisSentinel___construct, 0, 0, 0)
 	ZEND_ARG_INFO(0, options)
@@ -32,6 +32,7 @@ ZEND_END_ARG_INFO()
 
 #define arginfo_class_RedisSentinel_slaves arginfo_class_RedisSentinel_ckquorum
 
+
 ZEND_METHOD(RedisSentinel, __construct);
 ZEND_METHOD(RedisSentinel, ckquorum);
 ZEND_METHOD(RedisSentinel, failover);
@@ -45,6 +46,7 @@ ZEND_METHOD(RedisSentinel, reset);
 ZEND_METHOD(RedisSentinel, sentinels);
 ZEND_METHOD(RedisSentinel, slaves);
 
+
 static const zend_function_entry class_RedisSentinel_methods[] = {
 	ZEND_ME(RedisSentinel, __construct, arginfo_class_RedisSentinel___construct, ZEND_ACC_PUBLIC)
 	ZEND_ME(RedisSentinel, ckquorum, arginfo_class_RedisSentinel_ckquorum, ZEND_ACC_PUBLIC)
@@ -66,11 +68,7 @@ static zend_class_entry *register_class_RedisSentinel(void)
 	zend_class_entry ce, *class_entry;
 
 	INIT_CLASS_ENTRY(ce, "RedisSentinel", class_RedisSentinel_methods);
-#if (PHP_VERSION_ID >= 80400)
-	class_entry = zend_register_internal_class_with_flags(&ce, NULL, 0);
-#else
 	class_entry = zend_register_internal_class_ex(&ce, NULL);
-#endif
 
 	return class_entry;
 }
diff --git a/sentinel.md b/sentinel.md
@@ -12,6 +12,7 @@ Redis Sentinel also provides other collateral tasks such as monitoring, notifica
 
 *host*: String, IP address or hostname  
 *port*: Int (optional, default is 26379)  
+*hosts*: Array of `['host' => string, 'port' => int]` entries (optional). When provided, `host` and `port` are ignored and the client automatically falls back to the next host on network failure. See [Multi-host support](#multi-host-support) below.  
 *timeout*: Float, value in seconds (optional, default is 0 meaning unlimited)  
 *persistent*: String, persistent connection id (optional, default is NULL meaning not persistent)  
 *retry_interval*: Int, value in milliseconds (optional, default is 0)  
@@ -59,6 +60,36 @@ $sentinel = new RedisSentinel([
 ]); // connect sentinel with password authentication
 ~~~
 
+### Multi-host support
+-----
+
+For high-availability deployments (Kubernetes, multi-AZ), `RedisSentinel` accepts a `hosts` array of Sentinel endpoints. On network failure the client transparently falls back to the next entry in the list, so a single dead Sentinel no longer takes down the client.
+
+~~~php
+$sentinel = new RedisSentinel([
+  'hosts' => [
+    ['host' => '10.0.0.1', 'port' => 26379],
+    ['host' => '10.0.0.2', 'port' => 26379],
+    ['host' => '10.0.0.3', 'port' => 26379],
+  ],
+  'connectTimeout' => 0.1,
+  'auth' => 'secret',
+]);
+
+// Auto-falls-back to a reachable host if 10.0.0.1 is down.
+$master = $sentinel->getMasterAddrByName('mymaster');
+~~~
+
+##### *Semantics*
+
+* When `hosts` is provided, `host` and `port` are ignored.
+* The client tries hosts in order. The first reachable host is used for all subsequent calls ("sticky" connection).
+* If the current host becomes unreachable during a method call, the client transparently advances to the next host in the list and retries the call once.
+* Skipped hosts are NOT revisited for the lifetime of the `RedisSentinel` instance.
+* When all hosts are exhausted, a `RedisException` is thrown with a message mentioning the host count.
+* Retry is triggered only on network errors (connection refused, socket EOF, stream broken). Redis protocol errors (NOAUTH, WRONGPASS, unknown command) are propagated without retry.
+* Validation errors at construct time (empty `hosts`, missing `host` key, wrong types, `hosts` too large) throw `RedisException`, consistent with the rest of phpredis.
+
 ##### *Examples for versions older than 6.0*
 
 ~~~php