Skip to content

Commit ae5ceaf

Browse files
GirgiasKentarouTakeda
Girgias
and
KentarouTakeda
committed
Document new Pdo\Pgsql methods which did not exist previously
Co-authored-by: KentarouTakeda <[email protected]>
1 parent 50b5d3f commit ae5ceaf

File tree

6 files changed

+232
-7
lines changed

6 files changed

+232
-7
lines changed

‎reference/pdo_pgsql/pdo/pgsql/escapeidentifier.xml

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<refentry xml:id="pdo-pgsql.escapeidentifier" xmlns="http://docbook.org/ns/docbook">
3+
<refnamediv>
4+
<refname>Pdo\Pgsql::escapeIdentifier</refname>
5+
<refpurpose>Escapes a string for use as an SQL identifier</refpurpose>
6+
</refnamediv>
7+
8+
<refsect1 role="description">
9+
&reftitle.description;
10+
<methodsynopsis role="Pdo\\Pgsql">
11+
<modifier>public</modifier> <type>string</type><methodname>Pdo\Pgsql::escapeIdentifier</methodname>
12+
<methodparam><type>string</type><parameter>input</parameter></methodparam>
13+
</methodsynopsis>
14+
<simpara>
15+
Escapes a string for use as an SQL identifier, such as a table, column, or function name.
16+
This is useful when a user-supplied identifier might contain special characters
17+
that would otherwise not be interpreted as part of the identifier by the SQL parser,
18+
or when the identifier might contain upper case characters whose case should be preserved.
19+
</simpara>
20+
</refsect1>
21+
22+
<refsect1 role="parameters">
23+
&reftitle.parameters;
24+
<variablelist>
25+
<varlistentry>
26+
<term><parameter>input</parameter></term>
27+
<listitem>
28+
<simpara>
29+
A <type>string</type> containing text to be escaped.
30+
</simpara>
31+
</listitem>
32+
</varlistentry>
33+
</variablelist>
34+
</refsect1>
35+
36+
<refsect1 role="returnvalues">
37+
&reftitle.returnvalues;
38+
<simpara>
39+
A <type>string</type> containing the escaped data.
40+
</simpara>
41+
</refsect1>
42+
43+
<refsect1 role="examples">
44+
&reftitle.examples;
45+
<example xml:id="pdo-pgsql.escapeidentifier.example.basic">
46+
<title><methodname>Pdo\Pgsql::escapeIdentifier</methodname> example</title>
47+
<programlisting role="php">
48+
<![CDATA[
49+
<?php
50+
$pdo = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
51+
52+
$unescapedTableName = 'UnescapedTableName';
53+
$pdo->exec("CREATE TABLE $unescapedTableName ()");
54+
55+
$escapedTableName = $pdo->escapeIdentifier('EscapedTableName');
56+
$pdo->exec("CREATE TABLE $escapedTableName ()");
57+
58+
$statement = $pdo->query(
59+
"SELECT relname FROM pg_stat_user_tables WHERE relname ilike '%tablename'"
60+
);
61+
62+
var_export($statement->fetchAll(PDO::FETCH_COLUMN, 0));
63+
64+
$tableNameWithSymbols = 'Table-Name-With-Symbols';
65+
$pdo->exec("CREATE TABLE $tableNameWithSymbols ()");
66+
?>
67+
]]>
68+
</programlisting>
69+
&example.outputs.similar;
70+
<screen>
71+
<![CDATA[
72+
array (
73+
0 => 'unescapedtablename',
74+
1 => 'EscapedTableName',
75+
)
76+
Fatal error: Uncaught PDOException: SQLSTATE[42601]: Syntax error: 7 ERROR: syntax error at or near "Table"
77+
LINE 1: CREATE TABLE Table-Name-With-Symbols ()
78+
]]>
79+
</screen>
80+
</example>
81+
</refsect1>
82+
83+
<refsect1 role="seealso">
84+
&reftitle.seealso;
85+
<simplelist>
86+
<member><methodname>PDO::quote</methodname></member>
87+
</simplelist>
88+
</refsect1>
89+
90+
</refentry>
91+
<!-- Keep this comment at the end of the file
92+
Local variables:
93+
mode: sgml
94+
sgml-omittag:t
95+
sgml-shorttag:t
96+
sgml-minimize-attributes:nil
97+
sgml-always-quote-attributes:t
98+
sgml-indent-step:1
99+
sgml-indent-data:t
100+
indent-tabs-mode:nil
101+
sgml-parent-document:nil
102+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
103+
sgml-exposed-tags:nil
104+
sgml-local-catalogs:nil
105+
sgml-local-ecat-files:nil
106+
End:
107+
vim600: syn=xml fen fdm=syntax fdl=2 si
108+
vim: et tw=78 syn=sgml
109+
vi: ts=1 sw=1
110+
-->

‎reference/pdo_pgsql/pdo/pgsql/getpid.xml

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<refentry xml:id="pdo-pgsql.getpid" xmlns="http://docbook.org/ns/docbook">
33
<refnamediv>
44
<refname>Pdo\Pgsql::getPid</refname>
5-
<refpurpose>Get the server PID</refpurpose>
5+
<refpurpose>Get the PID of the backend process handling this connection</refpurpose>
66
</refnamediv>
77

88
<refsect1 role="description">
@@ -12,7 +12,9 @@
1212
<void/>
1313
</methodsynopsis>
1414
<simpara>
15-
Returns the server's PID.
15+
Returns the PID of the backend process handling this connection.
16+
Note that the PID belongs to a process executing on the database server host,
17+
not the local host.
1618
</simpara>
1719
</refsect1>
1820

@@ -24,7 +26,7 @@
2426
<refsect1 role="returnvalues">
2527
&reftitle.returnvalues;
2628
<simpara>
27-
Returns the server's PID as an <type>int</type>.
29+
Returns the PID as an <type>int</type>.
2830
</simpara>
2931
</refsect1>
3032
</refentry>

‎reference/pdo_pgsql/pdo/pgsql/lobcreate.xml

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
</methodsynopsis>
1414
<simpara>
1515
<methodname>Pdo\Pgsql::lobCreate</methodname> creates a large object
16-
and returns the ODI which refers to it.
16+
and returns the OID which refers to it.
1717
It can be opened to read or write data with
1818
<methodname>Pdo\Pgsql::lobOpen</methodname>.
1919
</simpara>
@@ -26,10 +26,11 @@
2626
<simpara>
2727
Large objects are cumbersome to use.
2828
Indeed, it is required that <methodname>Pdo\Pgsql::lobUnlink</methodname>
29-
is called prior to deleting the last row referencing the OID in the whole database.
29+
is called prior to deleting the last row referencing the OID in the entire database;
30+
otherwise, unreferenced large objects will remain on the server indefinitely.
3031
Moreover, large objects have no access controls.
3132
An alternative is the bytea column type, which can be up to 1GB in size,
32-
and this row type transparently manage the storage for optimal row size.
33+
and this column type transparently manages the storage for optimal row size.
3334
</simpara>
3435
<note>
3536
<simpara>

‎reference/pdo_pgsql/pdo/pgsql/lobunlink.xml

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,6 @@
4545
<example xml:id="pdo-pgsql.lobunlink.example.basic">
4646
<title><methodname>Pdo\Pgsql::lobUnlink</methodname> example</title>
4747
<simpara>
48-
Description.
4948
This example unlinks a large object from the database prior to deleting
5049
the row that references it from the blobs table are used in the examples of
5150
<methodname>Pdo\Pgsql::lobCreate</methodname> and

‎reference/pdo_pgsql/pdo/pgsql/setnoticecallback.xml

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<refentry xml:id="pdo-pgsql.setnoticecallback" xmlns="http://docbook.org/ns/docbook">
3+
<refnamediv>
4+
<refname>Pdo\Pgsql::setNoticeCallback</refname>
5+
<refpurpose>Set a callback to handle notice and warning messages generated by the backend</refpurpose>
6+
</refnamediv>
7+
8+
<refsect1 role="description">
9+
&reftitle.description;
10+
<methodsynopsis role="Pdo\\Pgsql">
11+
<modifier>public</modifier> <type>void</type><methodname>Pdo\Pgsql::setNoticeCallback</methodname>
12+
<methodparam><type class="union"><type>callable</type><type>null</type></type><parameter>callback</parameter></methodparam>
13+
</methodsynopsis>
14+
<simpara>
15+
Set a callback to handle notice and warning messages generated by the backend.
16+
This includes messages emitted by PostgreSQL itself,
17+
as well as those raised by user-defined SQL functions using <literal>RAISE</literal>.
18+
Please note that the actual receipt of these messages
19+
depends on the backend setting <literal>client_min_messages</literal>.
20+
</simpara>
21+
</refsect1>
22+
23+
<refsect1 role="parameters">
24+
&reftitle.parameters;
25+
<variablelist>
26+
<varlistentry>
27+
<term><parameter>callback</parameter></term>
28+
<listitem>
29+
<simpara>
30+
If &null; is passed, the handler is reset to its default state.
31+
</simpara>
32+
<para>
33+
Otherwise, the handler is a callback with the following signature:
34+
<methodsynopsis>
35+
<type>void</type><methodname><replaceable>handler</replaceable></methodname>
36+
<methodparam><type>string</type><parameter>message</parameter></methodparam>
37+
</methodsynopsis>
38+
<variablelist role="function_parameters">
39+
<varlistentry>
40+
<term><parameter>message</parameter></term>
41+
<listitem>
42+
<simpara>
43+
A message generated by the backend.
44+
</simpara>
45+
</listitem>
46+
</varlistentry>
47+
</variablelist>
48+
</para>
49+
</listitem>
50+
</varlistentry>
51+
</variablelist>
52+
</refsect1>
53+
54+
<refsect1 role="returnvalues">
55+
&reftitle.returnvalues;
56+
<simpara>
57+
&return.void;
58+
</simpara>
59+
</refsect1>
60+
61+
<refsect1 role="examples">
62+
&reftitle.examples;
63+
<example xml:id="pdo-pgsql.setnoticecallback.example.basic">
64+
<title><methodname>Pdo\Pgsql::setNoticeCallback</methodname> example</title>
65+
<programlisting role="php">
66+
<![CDATA[
67+
<?php
68+
<?php
69+
$pdo = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
70+
71+
$pdo->exec('CREATE TABLE parent(id int primary key)');
72+
$pdo->exec('CREATE TABLE child(id int references parent)');
73+
74+
$pdo->setNoticeCallback(function ($message) {
75+
echo $message;
76+
});
77+
78+
$pdo->exec('TRUNCATE parent CASCADE');
79+
?>
80+
]]>
81+
</programlisting>
82+
&example.outputs.similar;
83+
<screen>
84+
<![CDATA[
85+
NOTICE: truncate cascades to table "child"
86+
]]>
87+
</screen>
88+
</example>
89+
</refsect1>
90+
91+
</refentry>
92+
<!-- Keep this comment at the end of the file
93+
Local variables:
94+
mode: sgml
95+
sgml-omittag:t
96+
sgml-shorttag:t
97+
sgml-minimize-attributes:nil
98+
sgml-always-quote-attributes:t
99+
sgml-indent-step:1
100+
sgml-indent-data:t
101+
indent-tabs-mode:nil
102+
sgml-parent-document:nil
103+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
104+
sgml-exposed-tags:nil
105+
sgml-local-catalogs:nil
106+
sgml-local-ecat-files:nil
107+
End:
108+
vim600: syn=xml fen fdm=syntax fdl=2 si
109+
vim: et tw=78 syn=sgml
110+
vi: ts=1 sw=1
111+
-->

‎reference/pdo_pgsql/versions.xml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,13 @@
99
<function name="pdo\pgsql::copyfromfile" from="PHP 8 &gt;= 8.4.0"/>
1010
<function name="pdo\pgsql::copytoarray" from="PHP 8 &gt;= 8.4.0"/>
1111
<function name="pdo\pgsql::copytofile" from="PHP 8 &gt;= 8.4.0"/>
12+
<function name="pdo\pgsql::escapeidentifier" from="PHP 8 &gt;= 8.4.0"/>
1213
<function name="pdo\pgsql::getnotify" from="PHP 8 &gt;= 8.4.0"/>
1314
<function name="pdo\pgsql::getpid" from="PHP 8 &gt;= 8.4.0"/>
1415
<function name="pdo\pgsql::lobcreate" from="PHP 8 &gt;= 8.4.0"/>
1516
<function name="pdo\pgsql::lobopen" from="PHP 8 &gt;= 8.4.0"/>
1617
<function name="pdo\pgsql::lobunlink" from="PHP 8 &gt;= 8.4.0"/>
18+
<function name="pdo\pgsql::setnoticecallback" from="PHP 8 &gt;= 8.4.0"/>
1719
</versions>
1820
<!-- Keep this comment at the end of the file
1921
Local variables:

0 commit comments

Comments
 (0)