Document new Pdo\Pgsql methods which did not exist previously

Co-authored-by: KentarouTakeda <[email protected]>
php · Nov 24, 2024 · 4231a4d · 4231a4d
1 parent 50b5d3f
commit 4231a4d
Show file tree

Hide file tree

Showing 6 changed files with 228 additions and 7 deletions.
diff --git a/reference/pdo_pgsql/pdo/pgsql/escapeidentifier.xml b/reference/pdo_pgsql/pdo/pgsql/escapeidentifier.xml
@@ -0,0 +1,110 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry xml:id="pdo-pgsql.escapeidentifier" xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+  <refname>Pdo\Pgsql::escapeIdentifier</refname>
+  <refpurpose>Escapes a string for use as an SQL identifier</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis role="Pdo\\Pgsql">
+   <modifier>public</modifier> <type>string</type><methodname>Pdo\Pgsql::escapeIdentifier</methodname>
+   <methodparam><type>string</type><parameter>input</parameter></methodparam>
+  </methodsynopsis>
+  <simpara>
+   Escapes a string for use as an SQL identifier, such as a table, column, or function name.
+   This is useful when a user-supplied identifier might contain special characters
+   that would otherwise not be interpreted as part of the identifier by the SQL parser,
+   or when the identifier might contain upper case characters whose case should be preserved.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>input</parameter></term>
+    <listitem>
+     <simpara>
+      A <type>string</type> containing text to be escaped.
+     </simpara>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <simpara>
+   A <type>string</type> containing the escaped data.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example xml:id="pdo-pgsql.escapeidentifier.example.basic">
+   <title><methodname>Pdo\Pgsql::escapeIdentifier</methodname> example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$pdo = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
+
+$unescapedTableName = 'UnescapedTableName';
+$pdo->exec("CREATE TABLE $unescapedTableName ()");
+
+$escapedTableName = $pdo->escapeIdentifier('EscapedTableName');
+$pdo->exec("CREATE TABLE $escapedTableName ()");
+
+$statement = $pdo->query(
+  "SELECT relname FROM pg_stat_user_tables WHERE relname ilike '%tablename'"
+);
+
+var_export($statement->fetchAll(PDO::FETCH_COLUMN, 0));
+
+$tableNameWithSymbols = 'Table-Name-With-Symbols';
+$pdo->exec("CREATE TABLE $tableNameWithSymbols ()");
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+array (
+  0 => 'unescapedtablename',
+  1 => 'EscapedTableName',
+)
+Fatal error: Uncaught PDOException: SQLSTATE[42601]: Syntax error: 7 ERROR:  syntax error at or near "Table"
+LINE 1: CREATE TABLE Table-Name-With-Symbols ()
+]]>
+   </screen>
+  </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>PDO::quote</methodname></member>
+  </simplelist>
+ </refsect1>
+
+</refentry>
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/pdo_pgsql/pdo/pgsql/getpid.xml b/reference/pdo_pgsql/pdo/pgsql/getpid.xml
@@ -2,7 +2,7 @@
 <refentry xml:id="pdo-pgsql.getpid" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>Pdo\Pgsql::getPid</refname>
-  <refpurpose>Get the server PID</refpurpose>
+  <refpurpose>Get the PID of the backend process handling this connection</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -12,7 +12,9 @@
    <void/>
   </methodsynopsis>
   <simpara>
-   Returns the server's PID.
+   Returns the PID of the backend process handling this connection.
+   Note that the PID belongs to a process executing on the database server host,
+   not the local host.
   </simpara>
  </refsect1>
 
@@ -24,7 +26,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <simpara>
-   Returns the server's PID as an <type>int</type>.
+   Returns the PID as an <type>int</type>.
   </simpara>
  </refsect1>
 </refentry>

diff --git a/reference/pdo_pgsql/pdo/pgsql/lobcreate.xml b/reference/pdo_pgsql/pdo/pgsql/lobcreate.xml
@@ -13,7 +13,7 @@
   </methodsynopsis>
   <simpara>
    <methodname>Pdo\Pgsql::lobCreate</methodname> creates a large object
-   and returns the ODI which refers to it.
+   and returns the OID which refers to it.
    It can be opened to read or write data with
    <methodname>Pdo\Pgsql::lobOpen</methodname>.
   </simpara>
@@ -26,10 +26,11 @@
   <simpara>
    Large objects are cumbersome to use.
    Indeed, it is required that <methodname>Pdo\Pgsql::lobUnlink</methodname>
-   is called prior to deleting the last row referencing the OID in the whole database.
+   is called prior to deleting the last row referencing the OID in the entire database;
+   otherwise, unreferenced large objects will remain on the server indefinitely.
    Moreover, large objects have no access controls.
    An alternative is the bytea column type, which can be up to 1GB in size,
-   and this row type transparently manage the storage for optimal row size.
+   and this column type transparently manages the storage for optimal row size.
   </simpara>
   <note>
    <simpara>

diff --git a/reference/pdo_pgsql/pdo/pgsql/lobunlink.xml b/reference/pdo_pgsql/pdo/pgsql/lobunlink.xml
@@ -45,7 +45,6 @@
   <example xml:id="pdo-pgsql.lobunlink.example.basic">
    <title><methodname>Pdo\Pgsql::lobUnlink</methodname> example</title>
    <simpara>
-    Description.
     This example unlinks a large object from the database prior to deleting
     the row that references it from the blobs table are used in the examples of
     <methodname>Pdo\Pgsql::lobCreate</methodname> and

diff --git a/reference/pdo_pgsql/pdo/pgsql/setnoticecallback.xml b/reference/pdo_pgsql/pdo/pgsql/setnoticecallback.xml
@@ -0,0 +1,107 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry xml:id="pdo-pgsql.setnoticecallback" xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+  <refname>Pdo\Pgsql::setNoticeCallback</refname>
+  <refpurpose>Set a callback to handle notice and warning messages generated by the backend</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis role="Pdo\\Pgsql">
+   <modifier>public</modifier> <type>void</type><methodname>Pdo\Pgsql::setNoticeCallback</methodname>
+   <methodparam><type class="union"><type>callable</type><type>null</type></type><parameter>callback</parameter></methodparam>
+  </methodsynopsis>
+  <simpara>
+   Description.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>callback</parameter></term>
+    <listitem>
+     <simpara>
+      If &null; is passed, the handler is reset to its default state.
+     </simpara>
+     <para>
+      Otherwise, the handler is a callback with the following signature:
+      <methodsynopsis>
+       <type>void</type><methodname><replaceable>handler</replaceable></methodname>
+       <methodparam><type>string</type><parameter>message</parameter></methodparam>
+      </methodsynopsis>
+      <variablelist role="function_parameters">
+       <varlistentry>
+        <term><parameter>message</parameter></term>
+        <listitem>
+         <simpara>
+          A message generated by the backend.
+         </simpara>
+        </listitem>
+       </varlistentry>
+      </variablelist>
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <simpara>
+   &return.void;
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example xml:id="pdo-pgsql.setnoticecallback.example.basic">
+   <title><methodname>Pdo\Pgsql::setNoticeCallback</methodname> example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+<?php
+$pdo = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
+
+$pdo->exec('CREATE TABLE parent(id int primary key)');
+$pdo->exec('CREATE TABLE child(id int references parent)');
+
+$pdo->setNoticeCallback(function ($message) {
+    echo $message;
+});
+
+$pdo->exec('TRUNCATE parent CASCADE');
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+NOTICE:  truncate cascades to table "child"
+]]>
+   </screen>
+  </example>
+ </refsect1>
+
+</refentry>
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/pdo_pgsql/versions.xml b/reference/pdo_pgsql/versions.xml
@@ -9,11 +9,13 @@
  <function name="pdo\pgsql::copyfromfile" from="PHP 8 &gt;= 8.4.0"/>
  <function name="pdo\pgsql::copytoarray" from="PHP 8 &gt;= 8.4.0"/>
  <function name="pdo\pgsql::copytofile" from="PHP 8 &gt;= 8.4.0"/>
+ <function name="pdo\pgsql::escapeidentifier" from="PHP 8 &gt;= 8.4.0"/>
  <function name="pdo\pgsql::getnotify" from="PHP 8 &gt;= 8.4.0"/>
  <function name="pdo\pgsql::getpid" from="PHP 8 &gt;= 8.4.0"/>
  <function name="pdo\pgsql::lobcreate" from="PHP 8 &gt;= 8.4.0"/>
  <function name="pdo\pgsql::lobopen" from="PHP 8 &gt;= 8.4.0"/>
  <function name="pdo\pgsql::lobunlink" from="PHP 8 &gt;= 8.4.0"/>
+ <function name="pdo\pgsql::setnoticecallback" from="PHP 8 &gt;= 8.4.0"/>
 </versions>
 <!-- Keep this comment at the end of the file
 Local variables: