From 40607ecfc2f5158200bd985be369afe27d8841cb Mon Sep 17 00:00:00 2001
From: AllenJB <AllenJB@users.noreply.github.com>
Date: Sat, 4 Oct 2025 17:18:11 +0100
Subject: [PATCH 1/7] PDO: Add warning about (lack of) persistent connection
 cleanup (based on https://github.com/php/doc-en/issues/4540 )

---
 reference/pdo/connections.xml | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/reference/pdo/connections.xml b/reference/pdo/connections.xml
index dae512b9fce3..2b709b6068b7 100644
--- a/reference/pdo/connections.xml
+++ b/reference/pdo/connections.xml
@@ -130,6 +130,12 @@ $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass, array(
    object, the driver will not use persistent connections.
   </para>
  </note>
+ <warning>
+  <para>
+   PDO does not perform any cleanup of persistent connections. Temporary tables, locks, transactions and other stateful
+   changes may remain from previous usage of the connection, causing unexpected problems.
+  </para>
+ </warning>
  <note>
   <para>
    If you're using the PDO ODBC driver and your ODBC libraries support ODBC

From b98124ddee337ac18d48b0afa66f8bd54449a2e9 Mon Sep 17 00:00:00 2001
From: AllenJB <AllenJB@users.noreply.github.com>
Date: Sun, 5 Oct 2025 10:01:41 +0100
Subject: [PATCH 2/7] PDO persistent connection warning: Add link to Persistent
 DB Connections page

---
 reference/pdo/connections.xml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/reference/pdo/connections.xml b/reference/pdo/connections.xml
index 2b709b6068b7..8b9291a65d58 100644
--- a/reference/pdo/connections.xml
+++ b/reference/pdo/connections.xml
@@ -133,7 +133,8 @@ $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass, array(
  <warning>
   <para>
    PDO does not perform any cleanup of persistent connections. Temporary tables, locks, transactions and other stateful
-   changes may remain from previous usage of the connection, causing unexpected problems.
+   changes may remain from previous usage of the connection, causing unexpected problems. See the
+   <link linkend="features.persistent-connections">Persistent Database Connections</link> section for more information.
   </para>
  </warning>
  <note>

From f14fd51e19e86890932a7ba0823a2151c8a5fc92 Mon Sep 17 00:00:00 2001
From: AllenJB <AllenJB@users.noreply.github.com>
Date: Sun, 5 Oct 2025 10:39:00 +0100
Subject: [PATCH 3/7] Persistent connections: Add links to relevant mysqli and
 PDO pages

---
 features/persistent-connections.xml | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/features/persistent-connections.xml b/features/persistent-connections.xml
index b6577d276017..c115670607df 100644
--- a/features/persistent-connections.xml
+++ b/features/persistent-connections.xml
@@ -121,11 +121,21 @@
    probably will) change the efficiency of the script, but not its
    behavior!
   </simpara>
-  <para>
-   See also <function>ibase_pconnect</function>, <function>ociplogon</function>,
-   <function>odbc_pconnect</function>, <function>oci_pconnect</function>,
-   <function>pfsockopen</function>, and <function>pg_pconnect</function>.
-  </para>
+  <simplesect role="seealso">
+   &reftitle.seealso;
+   <para>
+    <simplelist>
+     <member><function>ibase_pconnect</function></member>
+     <member><function>ociplogon</function></member>
+     <member><function>odbc_pconnect</function></member>
+     <member><function>oci_pconnect</function></member>
+     <member><function>pfsockopen</function></member>
+     <member><function>pg_connect</function></member>
+     <member><link linkend="mysqli.persistconns">MySQLi and Persistent Connections</link></member>
+     <member><link linkend="pdo.connections">PDO Connection Management</link></member>
+    </simplelist>
+   </para>
+  </simplesect>
  </chapter>
 
 <!-- Keep this comment at the end of the file

From 547f1dc402b9060a87248bfb12d7478e7e55c73a Mon Sep 17 00:00:00 2001
From: AllenJB <AllenJB@users.noreply.github.com>
Date: Sun, 5 Oct 2025 10:56:13 +0100
Subject: [PATCH 4/7] Persistent connections: Fix order of see also links to be
 alpha, and remove link to deprecated alias

---
 features/persistent-connections.xml | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/features/persistent-connections.xml b/features/persistent-connections.xml
index c115670607df..c2f5694a2993 100644
--- a/features/persistent-connections.xml
+++ b/features/persistent-connections.xml
@@ -126,9 +126,8 @@
    <para>
     <simplelist>
      <member><function>ibase_pconnect</function></member>
-     <member><function>ociplogon</function></member>
-     <member><function>odbc_pconnect</function></member>
      <member><function>oci_pconnect</function></member>
+     <member><function>odbc_pconnect</function></member>
      <member><function>pfsockopen</function></member>
      <member><function>pg_connect</function></member>
      <member><link linkend="mysqli.persistconns">MySQLi and Persistent Connections</link></member>

From b7af3ddd50bddc7f83dd8fb9ea4b5a2f0f64ac9c Mon Sep 17 00:00:00 2001
From: AllenJB <AllenJB@users.noreply.github.com>
Date: Sun, 5 Oct 2025 12:00:45 +0100
Subject: [PATCH 5/7] Persistent connections: Break up the content and attempt
 to better spell out the potential issues

---
 features/persistent-connections.xml | 118 +++++++++++++++++-----------
 1 file changed, 72 insertions(+), 46 deletions(-)

diff --git a/features/persistent-connections.xml b/features/persistent-connections.xml
index c2f5694a2993..fa6d9afb1331 100644
--- a/features/persistent-connections.xml
+++ b/features/persistent-connections.xml
@@ -3,6 +3,8 @@
  <chapter xml:id="features.persistent-connections" xmlns="http://docbook.org/ns/docbook">
   <title>Persistent Database Connections</title>
 
+ <simplesect>
+  <title>What are Persistent Connections?</title>
   <simpara>
    Persistent connections are links that do not close when the
    execution of your script ends. When a persistent connection is
@@ -20,13 +22,14 @@
    do <emphasis>not</emphasis> give you an ability to build up a
    transaction efficiently, and they don't do a whole lot of other
    things. In fact, to be extremely clear about the subject,
-   persistent connections don't give you <emphasis>any</emphasis>
+   persistent connections don't give you<emphasis>any</emphasis>
    functionality that wasn't possible with their non-persistent
    brothers.
   </simpara>
-  <simpara>
-   Why?
-  </simpara> 
+ </simplesect>
+
+ <simplesect xml:id="persistent-connections.web">
+  <title>Web Requests</title>
   <simpara>
    This has to do with the way web servers work. There are three ways
    in which your web server can utilize PHP to generate web pages.
@@ -42,33 +45,43 @@
   </simpara>
   <simpara>
    The second, and most popular, method is to run PHP as a module in a
-   multiprocess web server, which currently only includes Apache. A
-   multiprocess server typically has one process (the parent) which
+   multiprocess web server, which currently only includes Apache, or PHP-FPM.
+   A multiprocess server typically has one process (the parent) which
    coordinates a set of processes (its children) who actually do the
    work of serving up web pages. When a request comes in from a
    client, it is handed off to one of the children that is not already
    serving another client. This means that when the same client makes
    a second request to the server, it may be served by a different
-   child process than the first time. When opening a persistent connection, 
-   every following page requesting SQL services can reuse the same 
+   child process than the first time. When opening a persistent connection,
+   every following page requesting SQL services can reuse the same
    established connection to the SQL server.
   </simpara>
   <simpara>
-   The last method is to use PHP as a plug-in for a multithreaded web
-   server. Currently PHP has support for WSAPI, and NSAPI (on
-   Windows), which all allow PHP to be used as a plug-in on multithreaded
-   servers like Netscape FastTrack (iPlanet), Microsoft's Internet Information
-   Server (IIS), and O'Reilly's WebSite Pro. The behavior is essentially
-   the same as for the multiprocess model described before.
+   The last method is to use PHP as a plug-in for a multithreaded web server.
+   Currently PHP has support for WSAPI, and NSAPI (on Windows), which all
+   allow PHP to be used as a plug-in on multithreaded servers like Microsoft's
+   Internet Information Server (IIS). The behavior is essentially the same as
+   for the multiprocess model described before.
   </simpara>
+ </simplesect>
+
+ <simplesect xml:id="persistent-connections.cli">
+  <title>Commandline Processes</title>
   <simpara>
-   If persistent connections don't have any added functionality, what
-   are they good for?
+   As commandline PHP uses a new process for each script, persistent
+   connections are not shared between commandline scripts, so there is no
+   value in using them in (short-lived) scripts such as crons or commands.
+   However, they may be useful if you're writing a long-running application
+   server that serves many requests (or other connections) and each may need
+   their own database connection.
   </simpara>
+ </simplesect>
+
+ <simplesect xml:id="persistent-connections.why">
+  <title>Why Use Them?</title>
   <simpara>
-   The answer here is extremely simple -- efficiency. Persistent
-   connections are good if the overhead to create a link to your SQL
-   server is high. Whether or not this overhead is really high depends
+   Persistent connections are good if the overhead to create a link to your
+   SQL server is high. Whether or not this overhead is really high depends
    on many factors. Like, what kind of database it is, whether or not
    it sits on the same computer on which your web server sits, how
    loaded the machine the SQL server sits on is and so forth. The
@@ -83,6 +96,10 @@
    you'd have 20 different connections to the SQL server, one from
    each child.
   </simpara>
+ </simplesect>
+
+ <simplesect xml:id="persistent-connections.drawbacks.conn-limits">
+  <title>Potential Drawbacks: Connection Limits</title>
   <simpara>
    Note, however, that this can have some drawbacks if you are using a
    database with connection limits that are exceeded by persistent
@@ -92,36 +109,45 @@
    bugs in your scripts which do not allow the connections to shut
    down (such as infinite loops), the database with only 16 connections
    may be rapidly swamped. Check your database documentation for
-   information on handling abandoned or idle connections.
+   information on handling abandoned or idle connections (timeouts).
+  </simpara>
+ </simplesect>
+
+ <simplesect xml:id="persistent-connections.drawbacks.state">
+  <title>Potential Drawbacks: Cleanup / State Management</title>
+  <simpara>
+   Depending on your application and the database / extension you're using you
+   may need to ensure that the state of connections is cleaned up. Changes
+   that may leave connections in an unexpected state include:
   </simpara>
-  <warning>
-   <simpara>
-    There are a couple of additional caveats to keep in mind when
-    using persistent connections. One is that when using table
-    locking on a persistent connection, if the script for whatever
-    reason cannot release the lock, then subsequent scripts using the
-    same connection will block indefinitely and may require that you
-    either restart the httpd server or the database server. Another is
-    that when using transactions, a transaction block will also carry
-    over to the next script which uses that connection if script execution
-    ends before the transaction block does. In either case, you can
-    use <function>register_shutdown_function</function> to register a
-    simple cleanup function to unlock your tables or roll back your
-    transactions. Better yet, avoid the problem entirely by not using
-    persistent connections in scripts which use table locks or
-    transactions (you can still use them elsewhere).
-   </simpara>
-  </warning>
+  <simplelist>
+   <member>Selected / default database</member>
+   <member>Table locks</member>
+   <member>Unclosed transactions</member>
+   <member>Temporary tables</member>
+   <member>Connection specific settings or features such as profiling</member>
+  </simplelist>
   <simpara>
-   An important summary. Persistent connections were designed to have
-   one-to-one mapping to regular connections. That means that you
-   should <emphasis>always</emphasis> be able to replace persistent
-   connections with non-persistent connections, and it won't change
-   the way your script behaves. It <emphasis>may</emphasis> (and
-   probably will) change the efficiency of the script, but not its
-   behavior!
+   Table locks and transactions that are not cleaned up or closed may cause
+   other queries to be blocked indefinitely and / or cause subsequent reuse of
+   the connection to cause unexpected changes.
   </simpara>
-  <simplesect role="seealso">
+  <simpara>
+   Having the wrong database selected will cause subsequent reuse of the
+   connection to be unable to execute queries as expected (or execute them on
+   the wrong database if schemas are similar enough).
+  </simpara>
+  <simpara>
+   If temporary tables are not cleaned up, subsequent requests will not be able
+   to recreate the same table.
+  </simpara>
+  <simpara>
+   You can implement cleanup using class destructors or
+   <function>register_shutdown_function</function>.
+  </simpara>
+ </simplesect>
+
+ <simplesect role="seealso" xml:id="persistent-connections.seealso">
    &reftitle.seealso;
    <para>
     <simplelist>

From 128e3dc6254e851d9d03b7584a53b0350b355366 Mon Sep 17 00:00:00 2001
From: AllenJB <AllenJB@users.noreply.github.com>
Date: Sun, 5 Oct 2025 13:28:47 +0100
Subject: [PATCH 6/7] Persistent connections: Mention connection pooling
 proxies

---
 features/persistent-connections.xml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/features/persistent-connections.xml b/features/persistent-connections.xml
index fa6d9afb1331..86fc26e631e1 100644
--- a/features/persistent-connections.xml
+++ b/features/persistent-connections.xml
@@ -143,7 +143,9 @@
   </simpara>
   <simpara>
    You can implement cleanup using class destructors or
-   <function>register_shutdown_function</function>.
+   <function>register_shutdown_function</function>. You may also want to
+   consider dedicated connection pooling proxies that include this as part of
+   their functionality.
   </simpara>
  </simplesect>
 

From 08294aea208ecf901f762c97f6dad81699d28c61 Mon Sep 17 00:00:00 2001
From: AllenJB <AllenJB@users.noreply.github.com>
Date: Sun, 5 Oct 2025 15:38:21 +0100
Subject: [PATCH 7/7] Persistent connections: Review amendments

---
 features/persistent-connections.xml | 46 +++++++++++++----------------
 1 file changed, 20 insertions(+), 26 deletions(-)

diff --git a/features/persistent-connections.xml b/features/persistent-connections.xml
index 86fc26e631e1..3398ffa8209a 100644
--- a/features/persistent-connections.xml
+++ b/features/persistent-connections.xml
@@ -22,7 +22,7 @@
    do <emphasis>not</emphasis> give you an ability to build up a
    transaction efficiently, and they don't do a whole lot of other
    things. In fact, to be extremely clear about the subject,
-   persistent connections don't give you<emphasis>any</emphasis>
+   persistent connections don't give you <emphasis>any</emphasis>
    functionality that wasn't possible with their non-persistent
    brothers.
   </simpara>
@@ -31,8 +31,8 @@
  <simplesect xml:id="persistent-connections.web">
   <title>Web Requests</title>
   <simpara>
-   This has to do with the way web servers work. There are three ways
-   in which your web server can utilize PHP to generate web pages.
+   There are two ways in which your web server can utilize PHP to generate
+   web pages:
   </simpara>
   <simpara>
    The first method is to use PHP as a CGI "wrapper". When run this
@@ -44,9 +44,9 @@
    to use persistent connections -- they simply don't persist.
   </simpara>
   <simpara>
-   The second, and most popular, method is to run PHP as a module in a
-   multiprocess web server, which currently only includes Apache, or PHP-FPM.
-   A multiprocess server typically has one process (the parent) which
+   The second, and most popular, method is to run PHP-FPM, or PHP as a module
+   in a multiprocess web server, which currently only includes Apache.
+   These setups typically have one process (the parent) which
    coordinates a set of processes (its children) who actually do the
    work of serving up web pages. When a request comes in from a
    client, it is handed off to one of the children that is not already
@@ -56,24 +56,17 @@
    every following page requesting SQL services can reuse the same
    established connection to the SQL server.
   </simpara>
-  <simpara>
-   The last method is to use PHP as a plug-in for a multithreaded web server.
-   Currently PHP has support for WSAPI, and NSAPI (on Windows), which all
-   allow PHP to be used as a plug-in on multithreaded servers like Microsoft's
-   Internet Information Server (IIS). The behavior is essentially the same as
-   for the multiprocess model described before.
-  </simpara>
  </simplesect>
 
  <simplesect xml:id="persistent-connections.cli">
-  <title>Commandline Processes</title>
+  <title>Command-line Processes</title>
   <simpara>
-   As commandline PHP uses a new process for each script, persistent
-   connections are not shared between commandline scripts, so there is no
-   value in using them in (short-lived) scripts such as crons or commands.
-   However, they may be useful if you're writing a long-running application
-   server that serves many requests (or other connections) and each may need
-   their own database connection.
+   As command-line PHP uses a new process for each script, persistent
+   connections are not shared between command-line scripts, so there is no
+   value in using them in transient scripts such as crons or commands.
+   However, they may be useful if, for example, you're writing a long-running
+   application server that serves many requests (or other connections) and each
+   may need their own database connection.
   </simpara>
  </simplesect>
 
@@ -114,22 +107,23 @@
  </simplesect>
 
  <simplesect xml:id="persistent-connections.drawbacks.state">
-  <title>Potential Drawbacks: Cleanup / State Management</title>
+  <title>Potential Drawbacks: Maintaining Connection State</title>
   <simpara>
-   Depending on your application and the database / extension you're using you
-   may need to ensure that the state of connections is cleaned up. Changes
-   that may leave connections in an unexpected state include:
+   Depending on your application and the database or extension you're using you
+   may need to ensure that the state of connections is cleaned up before the
+   script exits. Changes that may leave connections in an unexpected state
+   include:
   </simpara>
   <simplelist>
    <member>Selected / default database</member>
    <member>Table locks</member>
-   <member>Unclosed transactions</member>
+   <member>Uncommitted transactions</member>
    <member>Temporary tables</member>
    <member>Connection specific settings or features such as profiling</member>
   </simplelist>
   <simpara>
    Table locks and transactions that are not cleaned up or closed may cause
-   other queries to be blocked indefinitely and / or cause subsequent reuse of
+   other queries to be blocked indefinitely and/or cause subsequent reuse of
    the connection to cause unexpected changes.
   </simpara>
   <simpara>