reference/pgsql/functions/pg-delete.xml
c2eca73ef79ebe78cebb34053e41b565af504c4f
c2eca73ef79ebe78cebb34053e41b565af504c4f
...
...
@@ -1,6 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xml:id='function.pg-delete' xmlns="http://docbook.org/ns/docbook">
3
+
<refentry xml:id="function.pg-delete" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>pg_delete</refname>
6
6
<refpurpose>
...
...
@@ -11,17 +11,32 @@
11
11
<refsect1 role="description">
12
12
&reftitle.description;
13
13
<methodsynopsis>
14
-
<type>mixed</type><methodname>pg_delete</methodname>
15
-
<methodparam><type>resource</type><parameter>connection</parameter></methodparam>
14
+
<type class="union"><type>string</type><type>bool</type></type><methodname>pg_delete</methodname>
15
+
<methodparam><type>PgSql\Connection</type><parameter>connection</parameter></methodparam>
16
16
<methodparam><type>string</type><parameter>table_name</parameter></methodparam>
17
-
<methodparam><type>array</type><parameter>assoc_array</parameter></methodparam>
18
-
<methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>PGSQL_DML_EXEC</initializer></methodparam>
17
+
<methodparam><type>array</type><parameter>conditions</parameter></methodparam>
18
+
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>PGSQL_DML_EXEC</constant></initializer></methodparam>
19
19
</methodsynopsis>
20
20
<para>
21
-
<function>pg_delete</function> deletes records from a table specified by
22
-
the keys and values in <parameter>assoc_array</parameter>. If <parameter>options</parameter> is
23
-
specified, <function>pg_convert</function> is applied
24
-
to <parameter>assoc_array</parameter> with the specified options.
21
+
<function>pg_delete</function> deletes records from a table
22
+
specified by the keys and values in <parameter>conditions</parameter>.
23
+
</para>
24
+
<para>
25
+
If <parameter>flags</parameter> is specified,
26
+
<function>pg_convert</function> is applied to
27
+
<parameter>conditions</parameter> with the specified flags.
28
+
</para>
29
+
<para>
30
+
By default <function>pg_delete</function> passes raw values.
31
+
Values must be escaped or the <constant>PGSQL_DML_ESCAPE</constant> flag
32
+
must be specified in <parameter>flags</parameter>.
33
+
<constant>PGSQL_DML_ESCAPE</constant> quotes and escapes parameters/identifiers.
34
+
Therefore, table/column names become case sensitive.
35
+
</para>
36
+
<para>
37
+
Note that neither escape nor prepared query can protect LIKE query,
38
+
JSON, Array, Regex, etc. These parameters should be handled
39
+
according to their contexts. i.e. Escape/validate values.
25
40
</para>
26
41
</refsect1>
27
42
...
...
@@ -32,9 +47,7 @@
32
47
<varlistentry>
33
48
<term><parameter>connection</parameter></term>
34
49
<listitem>
35
-
<para>
36
-
PostgreSQL database connection resource.
37
-
</para>
50
+
&pgsql.parameter.connection;
38
51
</listitem>
39
52
</varlistentry>
40
53
<varlistentry>
...
...
@@ -46,7 +59,7 @@
46
59
</listitem>
47
60
</varlistentry>
48
61
<varlistentry>
49
-
<term><parameter>assoc_array</parameter></term>
62
+
<term><parameter>conditions</parameter></term>
50
63
<listitem>
51
64
<para>
52
65
An <type>array</type> whose keys are field names in the table <parameter>table_name</parameter>,
...
...
@@ -55,7 +68,7 @@
55
68
</listitem>
56
69
</varlistentry>
57
70
<varlistentry>
58
-
<term><parameter>options</parameter></term>
71
+
<term><parameter>flags</parameter></term>
59
72
<listitem>
60
73
<para>
61
74
Any number of <constant>PGSQL_CONV_FORCE_NULL</constant>,
...
...
@@ -64,7 +77,7 @@
64
77
<constant>PGSQL_DML_EXEC</constant>,
65
78
<constant>PGSQL_DML_ASYNC</constant> or
66
79
<constant>PGSQL_DML_STRING</constant> combined. If <constant>PGSQL_DML_STRING</constant> is part of the
67
-
<parameter>options</parameter> then query string is returned. When <constant>PGSQL_DML_NO_CONV</constant>
80
+
<parameter>flags</parameter> then query string is returned. When <constant>PGSQL_DML_NO_CONV</constant>
68
81
or <constant>PGSQL_DML_ESCAPE</constant> is set, it does not call <function>pg_convert</function> internally.
69
82
</para>
70
83
</listitem>
...
...
@@ -77,10 +90,27 @@
77
90
&reftitle.returnvalues;
78
91
<para>
79
92
&return.success; Returns <type>string</type> if <constant>PGSQL_DML_STRING</constant> is passed
80
-
via <parameter>options</parameter>.
93
+
via <parameter>flags</parameter>.
81
94
</para>
82
95
</refsect1>
83
96
97
+
<refsect1 role="changelog">
98
+
&reftitle.changelog;
99
+
<informaltable>
100
+
<tgroup cols="2">
101
+
<thead>
102
+
<row>
103
+
<entry>&Version;</entry>
104
+
<entry>&Description;</entry>
105
+
</row>
106
+
</thead>
107
+
<tbody>
108
+
&pgsql.changelog.connection-object;
109
+
</tbody>
110
+
</tgroup>
111
+
</informaltable>
112
+
</refsect1>
113
+
84
114
<refsect1 role="examples">
85
115
&reftitle.examples;
86
116
<para>
...
...
@@ -90,8 +120,10 @@
90
120
<![CDATA[
91
121
<?php
92
122
$db = pg_connect('dbname=foo');
93
-
// This is safe, since $_POST is converted automatically
94
-
$res = pg_delete($db, 'post_log', $_POST);
123
+
// This is safe somewhat, since all values are escaped.
124
+
// However PostgreSQL supports JSON/Array. These are not
125
+
// safe by neither escape nor prepared query.
126
+
$res = pg_delete($db, 'post_log', $_POST, PG_DML_ESCAPE);
95
127
if ($res) {
96
128
echo "POST data is deleted: $res\n";
97
129
} else {
...
...
@@ -104,38 +136,6 @@
104
136
</para>
105
137
</refsect1>
106
138
107
-
<refsect1 role="changelog">
108
-
&reftitle.changelog;
109
-
<para>
110
-
<informaltable>
111
-
<tgroup cols="2">
112
-
<thead>
113
-
<row>
114
-
<entry>&Version;</entry>
115
-
<entry>&Description;</entry>
116
-
</row>
117
-
</thead>
118
-
<tbody>
119
-
<row>
120
-
<entry>5.6.0</entry>
121
-
<entry>
122
-
No longer experimental. Added <constant>PGSQL_DML_ESCAPE</constant> constant,
123
-
&true;/&false; and &null; data type support.
124
-
</entry>
125
-
</row>
126
-
<row>
127
-
<entry>5.5.3/5.4.19</entry>
128
-
<entry>
129
-
Direct SQL injection to <parameter>table_name</parameter> and Indirect SQL
130
-
injection to identifiers are fixed.
131
-
</entry>
132
-
</row>
133
-
</tbody>
134
-
</tgroup>
135
-
</informaltable>
136
-
</para>
137
-
</refsect1>
138
-
139
139
<refsect1 role="seealso">
140
140
&reftitle.seealso;
141
141
<para>
...
...
@@ -145,7 +145,6 @@
145
145
</para>
146
146
</refsect1>
147
147
</refentry>
148
-
149
148
<!-- Keep this comment at the end of the file
150
149
Local variables:
151
150
mode: sgml
152
151