pdo_pgsql: document ATTR_PREFETCH lazy fetch, fix copyFromArray sig (#5629)

* pdo_pgsql: document ATTR_PREFETCH lazy fetch, fix copyFromArray signature

* Apply suggestion from @lacatoire

Co-authored-by: Louis-Arnaud <la.catoire@gmail.com>

* pdo_pgsql: fix ATTR_PREFETCH link and copyFromArray rows whitespace

---------

Co-authored-by: Louis-Arnaud <la.catoire@gmail.com>

Author: philip

reference/pdo/constants.xml

@@ -251,6 +251,13 @@
       setting of the prefetch size.  A larger prefetch size results in
       increased performance at the cost of higher memory usage.
      </simpara>
+     <simpara>
+      The PDO_PGSQL driver instead treats this attribute as a toggle: as of
+      PHP 8.5.0, a value of <literal>0</literal> enables lazy (single-row)
+      fetching; see the
+      <link linkend="pdo-pgsql.constants.attr-prefetch">PDO_PGSQL driver docs</link>
+      for details.
+     </simpara>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="pdo.constants.attr-timeout">

reference/pdo_pgsql/pdo-pgsql.xml

@@ -155,6 +155,32 @@
       </simpara>
      </listitem>
     </varlistentry>
+    <varlistentry xml:id="pdo-pgsql.constants.attr-prefetch">
+     <term><constant>PDO::ATTR_PREFETCH</constant></term>
+     <listitem>
+      <simpara>
+       As of PHP 8.5.0, setting this attribute to <literal>0</literal> enables
+       lazy (single-row) fetching: rows are retrieved from the server one at a
+       time as they are fetched, instead of buffering the whole result set in
+       memory before the first <methodname>PDOStatement::fetch</methodname>
+       call. This reduces memory usage for large result sets. Any other value
+       keeps the default buffered behavior.
+      </simpara>
+      <simpara>
+       It can be set per connection with
+       <methodname>PDO::setAttribute</methodname>, or per statement via
+       the <methodname>PDO::prepare</methodname> or
+       <methodname>PDO::query</methodname> driver options.
+      </simpara>
+      <caution>
+       <simpara>
+        In lazy mode, a connection can have only one active statement at a
+        time. Running another statement silently discards any unread rows of
+        the previous one; no error is raised.
+       </simpara>
+      </caution>
+     </listitem>
+    </varlistentry>
     <varlistentry xml:id="pdo-pgsql.constants.transaction-idle">
      <term><constant>Pdo\Pgsql::TRANSACTION_IDLE</constant></term>
      <listitem>

reference/pdo_pgsql/pdo/pgsql/copyfromarray.xml

@@ -10,7 +10,7 @@
   <methodsynopsis role="Pdo\\Pgsql">
    <modifier>public</modifier> <type>bool</type><methodname>Pdo\Pgsql::copyFromArray</methodname>
    <methodparam><type>string</type><parameter>tableName</parameter></methodparam>
-   <methodparam><type>array</type><parameter>rows</parameter></methodparam>
+   <methodparam><type class="union"><type>array</type><type>Traversable</type></type><parameter>rows</parameter></methodparam>
    <methodparam choice="opt"><type>string</type><parameter>separator</parameter><initializer>"\t"</initializer></methodparam>
    <methodparam choice="opt"><type>string</type><parameter>nullAs</parameter><initializer>"\\\\N"</initializer></methodparam>
    <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>fields</parameter><initializer>&null;</initializer></methodparam>
@@ -37,8 +37,9 @@
     <term><parameter>rows</parameter></term>
     <listitem>
      <simpara>
-      An indexed <type>array</type> of <type>string</type>s with fields
-      separated by <parameter>separator</parameter>.
+      An indexed <type>array</type> (or <type>Traversable</type>) of
+      <type>string</type>s with fields separated by
+      <parameter>separator</parameter>.
      </simpara>
     </listitem>
    </varlistentry>