From b61c134184ec335dd23f5483059985954640c810 Mon Sep 17 00:00:00 2001
From: Sergey Avseyev <sergey.avseyev@gmail.com>
Date: Thu, 5 Dec 2024 08:55:56 -0800
Subject: [PATCH 1/6] Add note about persistent connections

---
 MIGRATION_FROM_3_x.md | 51 ++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 48 insertions(+), 3 deletions(-)

diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md
index 25111518..68da1680 100644
--- a/MIGRATION_FROM_3_x.md
+++ b/MIGRATION_FROM_3_x.md
@@ -559,7 +559,7 @@ The table below shows correspondence of timeout values between `Bucket` object s
                 <ul>
                     <li>fatal</li>
                     <li>error</li>
-                    <li>wrning</li>
+                    <li>warning</li>
                     <li>info</li>
                     <li>debug</li>
                     <li>trace</li>
@@ -587,8 +587,53 @@ The table below shows correspondence of timeout values between `Bucket` object s
             <td>Removed</td>
         </tr>
         <tr>
-            <td>couchbase.pool.max_idle_time_sec</td>
-            <td>couchbase.persistent_timeout</td>
+<td>
+
+`couchbase.pool.max_idle_time_sec`
+
+Sets the interval that allowed for the persistent instance to be idle. The
+default is 60 seconds. The SDK associates reference counter with the instance
+uniquely identified by connection string and credentials. When reference
+counter reaches zero, the SDK records current time into idle timestamp of the
+instance. In the end of each request, the SDK will run cleanup process that
+will sweep all idle instances at that point in time.
+
+Persistent instances are useful for the cases that the PHP worker process is
+not being destroyed after serving the request, so that next request will not
+need to wait for instance to bootstrap if it uses the same connection string,
+bucket and credentials.
+</td>
+<td>
+
+`couchbase.persistent_timeout`
+
+SDKv4 is based on C++SDK. It has similar behavior when it comes to persistent
+instances. But instead running cleanup in the end of each request, it does
+cleanup only when the library need to create new connection and the number of
+existing connection have reached `couchbase.max_persistent`.
+
+By default both `couchbase.persistent_timeout` and `couchbase.max_persistent`
+equal to `-1`, which means that the instances will be destroyed naturally
+when the PHP process will exit.
+
+This behavior was not possible in SDKv3 because libcouchbase does not have any
+background threads, that can perform service tasks (like tracking configuration
+changes).
+
+So if `couchbase.max_persistent` is set to positive (or zero) value, the
+extension will run the cleanup tasks if number of existing instances, and will
+destroy all instances, that have expired.
+
+The expiration time for the instance is recorded when the instance is created
+or pulled from the cache, and equals to current time plus
+`couchbase.persistent_timeout`.
+
+For example, setting both `couchbase.persistent_timeout` and
+`couchbase.max_persistent` to zero will force extension to destroy all existing
+connections and always create new one. So the application have to be extra
+careful not to reuse destroyed connections by using equivalent of global
+singleton instance of the `\Couchbase\Cluster` object.
+</td>
         </tr>
         <tr>
             <td>couchbase.allow_fallback_to_bucket_connection</td>

From d73bb68fc63ed423346704bc258cf4a295747bed Mon Sep 17 00:00:00 2001
From: Sergey Avseyev <sergey.avseyev@gmail.com>
Date: Thu, 5 Dec 2024 18:58:07 +0000
Subject: [PATCH 2/6] Apply suggestions from code review

Co-authored-by: Ray Cardillo <1744144+raycardillo@users.noreply.github.com>
---
 MIGRATION_FROM_3_x.md | 36 ++++++++++++++++++------------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md
index 68da1680..49259475 100644
--- a/MIGRATION_FROM_3_x.md
+++ b/MIGRATION_FROM_3_x.md
@@ -591,15 +591,15 @@ The table below shows correspondence of timeout values between `Bucket` object s
 
 `couchbase.pool.max_idle_time_sec`
 
-Sets the interval that allowed for the persistent instance to be idle. The
-default is 60 seconds. The SDK associates reference counter with the instance
-uniquely identified by connection string and credentials. When reference
-counter reaches zero, the SDK records current time into idle timestamp of the
-instance. In the end of each request, the SDK will run cleanup process that
+Sets the maximum time that a persistent instance can be idle before being cleaned up. The
+default is 60 seconds. The SDK associates a reference counter with the instance
+uniquely identified by the connection string and credentials. When the reference
+counter reaches zero, the SDK records the current time into the idle timestamp of the
+instance. At the end of each request, the SDK runs a cleanup process that
 will sweep all idle instances at that point in time.
 
-Persistent instances are useful for the cases that the PHP worker process is
-not being destroyed after serving the request, so that next request will not
+Persistent instances are useful for cases when the PHP worker process is
+not destroyed after serving the request, so that next request will not
 need to wait for instance to bootstrap if it uses the same connection string,
 bucket and credentials.
 </td>
@@ -608,30 +608,30 @@ bucket and credentials.
 `couchbase.persistent_timeout`
 
 SDKv4 is based on C++SDK. It has similar behavior when it comes to persistent
-instances. But instead running cleanup in the end of each request, it does
+instances. But instead of running cleanup at the end of each request, it does
 cleanup only when the library need to create new connection and the number of
 existing connection have reached `couchbase.max_persistent`.
 
 By default both `couchbase.persistent_timeout` and `couchbase.max_persistent`
-equal to `-1`, which means that the instances will be destroyed naturally
+are set to `-1`, which means that the instances will be destroyed naturally
 when the PHP process will exit.
 
 This behavior was not possible in SDKv3 because libcouchbase does not have any
-background threads, that can perform service tasks (like tracking configuration
+background threads that can perform service tasks (like tracking configuration
 changes).
 
-So if `couchbase.max_persistent` is set to positive (or zero) value, the
-extension will run the cleanup tasks if number of existing instances, and will
-destroy all instances, that have expired.
+So if `couchbase.max_persistent` is set to a positive (or zero) value, the
+extension will run the cleanup tasks if the number of existing instances exceeds the max, and will
+destroy all instances that have expired.
 
 The expiration time for the instance is recorded when the instance is created
-or pulled from the cache, and equals to current time plus
+or pulled from the cache, and is set to the current time plus
 `couchbase.persistent_timeout`.
 
-For example, setting both `couchbase.persistent_timeout` and
-`couchbase.max_persistent` to zero will force extension to destroy all existing
-connections and always create new one. So the application have to be extra
-careful not to reuse destroyed connections by using equivalent of global
+Note that by setting both `couchbase.persistent_timeout` and
+`couchbase.max_persistent` to zero, this will force the extension to destroy all existing
+connections and always create a new one. If using this configuration, the application must be very
+careful not to reuse destroyed connections, perhaps by using the equivalent of a global
 singleton instance of the `\Couchbase\Cluster` object.
 </td>
         </tr>

From 852c3ab5e53599884f0629fbf902a7b13a02c631 Mon Sep 17 00:00:00 2001
From: Sergey Avseyev <sergey.avseyev@gmail.com>
Date: Thu, 5 Dec 2024 11:01:14 -0800
Subject: [PATCH 3/6] fix formatting

---
 MIGRATION_FROM_3_x.md | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md
index 49259475..16b5ab7e 100644
--- a/MIGRATION_FROM_3_x.md
+++ b/MIGRATION_FROM_3_x.md
@@ -621,18 +621,19 @@ background threads that can perform service tasks (like tracking configuration
 changes).
 
 So if `couchbase.max_persistent` is set to a positive (or zero) value, the
-extension will run the cleanup tasks if the number of existing instances exceeds the max, and will
-destroy all instances that have expired.
+extension will run the cleanup tasks if the number of existing instances
+exceeds the max, and will destroy all instances that have expired.
 
 The expiration time for the instance is recorded when the instance is created
 or pulled from the cache, and is set to the current time plus
 `couchbase.persistent_timeout`.
 
 Note that by setting both `couchbase.persistent_timeout` and
-`couchbase.max_persistent` to zero, this will force the extension to destroy all existing
-connections and always create a new one. If using this configuration, the application must be very
-careful not to reuse destroyed connections, perhaps by using the equivalent of a global
-singleton instance of the `\Couchbase\Cluster` object.
+`couchbase.max_persistent` to zero, this will force the extension to destroy
+all existing connections and always create a new one. If using this
+configuration, the application must be very careful not to reuse destroyed
+connections, perhaps by using the equivalent of a global singleton instance of
+the `\Couchbase\Cluster` object.
 </td>
         </tr>
         <tr>

From 9e2368e69d03696c16e3ac9880297bdd8290554f Mon Sep 17 00:00:00 2001
From: Sergey Avseyev <sergey.avseyev@gmail.com>
Date: Fri, 6 Dec 2024 15:12:22 -0800
Subject: [PATCH 4/6] Add link to PCBC-1018

---
 MIGRATION_FROM_3_x.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md
index 16b5ab7e..b6639f16 100644
--- a/MIGRATION_FROM_3_x.md
+++ b/MIGRATION_FROM_3_x.md
@@ -633,7 +633,9 @@ Note that by setting both `couchbase.persistent_timeout` and
 all existing connections and always create a new one. If using this
 configuration, the application must be very careful not to reuse destroyed
 connections, perhaps by using the equivalent of a global singleton instance of
-the `\Couchbase\Cluster` object.
+the `\Couchbase\Cluster` object. This issue was reported as
+[PCBC-1018](https://jira.issues.couchbase.com/browse/PCBC-1018) and fixed in
+4.2.6 release.
 </td>
         </tr>
         <tr>

From 54f1a8d47284f5b292f3fca5131fa246257f143a Mon Sep 17 00:00:00 2001
From: Sergey Avseyev <sergey.avseyev@gmail.com>
Date: Mon, 9 Dec 2024 17:31:24 +0000
Subject: [PATCH 5/6] Update MIGRATION_FROM_3_x.md

Co-authored-by: Mateusz <matt.wozakowski@gmail.com>
---
 MIGRATION_FROM_3_x.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md
index b6639f16..d6381ba6 100644
--- a/MIGRATION_FROM_3_x.md
+++ b/MIGRATION_FROM_3_x.md
@@ -600,7 +600,7 @@ will sweep all idle instances at that point in time.
 
 Persistent instances are useful for cases when the PHP worker process is
 not destroyed after serving the request, so that next request will not
-need to wait for instance to bootstrap if it uses the same connection string,
+need to wait for the instance to bootstrap if it uses the same connection string,
 bucket and credentials.
 </td>
 <td>

From 0f3f0a5005c1addc1bd4629e627cee4d1263f2a7 Mon Sep 17 00:00:00 2001
From: Sergey Avseyev <sergey.avseyev@gmail.com>
Date: Mon, 9 Dec 2024 17:31:32 +0000
Subject: [PATCH 6/6] Update MIGRATION_FROM_3_x.md

Co-authored-by: Mateusz <matt.wozakowski@gmail.com>
---
 MIGRATION_FROM_3_x.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md
index d6381ba6..b71baae8 100644
--- a/MIGRATION_FROM_3_x.md
+++ b/MIGRATION_FROM_3_x.md
@@ -609,7 +609,7 @@ bucket and credentials.
 
 SDKv4 is based on C++SDK. It has similar behavior when it comes to persistent
 instances. But instead of running cleanup at the end of each request, it does
-cleanup only when the library need to create new connection and the number of
+cleanup only when the library needs to create a new connection and the number of
 existing connection have reached `couchbase.max_persistent`.
 
 By default both `couchbase.persistent_timeout` and `couchbase.max_persistent`