reference/pgsql/functions/pg-update.xml
c2eca73ef79ebe78cebb34053e41b565af504c4f
...
...
@@ -1,7 +1,7 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
3
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.80 -->
4
-
<refentry xml:id='function.pg-update' xmlns="http://docbook.org/ns/docbook">
4
+
<refentry xml:id="function.pg-update" xmlns="http://docbook.org/ns/docbook">
5
5
<refnamediv>
6
6
<refname>pg_update</refname>
7
7
<refpurpose>
...
...
@@ -12,19 +12,33 @@
12
12
<refsect1 role="description">
13
13
&reftitle.description;
14
14
<methodsynopsis>
15
-
<type>mixed</type><methodname>pg_update</methodname>
16
-
<methodparam><type>resource</type><parameter>connection</parameter></methodparam>
15
+
<type class="union"><type>string</type><type>bool</type></type><methodname>pg_update</methodname>
16
+
<methodparam><type>PgSql\Connection</type><parameter>connection</parameter></methodparam>
17
17
<methodparam><type>string</type><parameter>table_name</parameter></methodparam>
18
-
<methodparam><type>array</type><parameter>data</parameter></methodparam>
19
-
<methodparam><type>array</type><parameter>condition</parameter></methodparam>
20
-
<methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>PGSQL_DML_EXEC</initializer></methodparam>
18
+
<methodparam><type>array</type><parameter>values</parameter></methodparam>
19
+
<methodparam><type>array</type><parameter>conditions</parameter></methodparam>
20
+
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>PGSQL_DML_EXEC</constant></initializer></methodparam>
21
21
</methodsynopsis>
22
22
<para>
23
23
<function>pg_update</function> updates records that matches
24
-
<literal>condition</literal> with <literal>data</literal>. If
25
-
<literal>options</literal> is specified,
24
+
<parameter>conditions</parameter> with <parameter>values</parameter>.
25
+
</para>
26
+
<para>
27
+
If <parameter>flags</parameter> is specified,
26
28
<function>pg_convert</function> is applied to
27
-
<literal>data</literal> with specified options.
29
+
<parameter>values</parameter> with the specified flags.
30
+
</para>
31
+
<para>
32
+
By default <function>pg_update</function> passes raw values.
33
+
Values must be escaped or the <constant>PGSQL_DML_ESCAPE</constant> flag
34
+
must be specified in <parameter>flags</parameter>.
35
+
<constant>PGSQL_DML_ESCAPE</constant> quotes and escapes parameters/identifiers.
36
+
Therefore, table/column names become case sensitive.
37
+
</para>
38
+
<para>
39
+
Note that neither escape nor prepared query can protect LIKE query,
40
+
JSON, Array, Regex, etc. These parameters should be handled
41
+
according to their contexts. i.e. Escape/validate values.
28
42
</para>
29
43
</refsect1>
30
44

...
...
@@ -35,9 +49,7 @@
35
49
<varlistentry>
36
50
<term><parameter>connection</parameter></term>
37
51
<listitem>
38
-
<para>
39
-
PostgreSQL database connection resource.
40
-
</para>
52
+
&pgsql.parameter.connection;
41
53
</listitem>
42
54
</varlistentry>
43
55
<varlistentry>
...
...
@@ -49,7 +61,7 @@
49
61
</listitem>
50
62
</varlistentry>
51
63
<varlistentry>
52
-
<term><parameter>data</parameter></term>
64
+
<term><parameter>values</parameter></term>
53
65
<listitem>
54
66
<para>
55
67
An <type>array</type> whose keys are field names in the table <parameter>table_name</parameter>,
...
...
@@ -58,7 +70,7 @@
58
70
</listitem>
59
71
</varlistentry>
60
72
<varlistentry>
61
-
<term><parameter>condition</parameter></term>
73
+
<term><parameter>conditions</parameter></term>
62
74
<listitem>
63
75
<para>
64
76
An <type>array</type> whose keys are field names in the table <parameter>table_name</parameter>,
...
...
@@ -67,7 +79,7 @@
67
79
</listitem>
68
80
</varlistentry>
69
81
<varlistentry>
70
-
<term><parameter>options</parameter></term>
82
+
<term><parameter>flags</parameter></term>
71
83
<listitem>
72
84
<para>
73
85
Any number of <constant>PGSQL_CONV_FORCE_NULL</constant>,
...
...
@@ -76,7 +88,7 @@
76
88
<constant>PGSQL_DML_EXEC</constant>,
77
89
<constant>PGSQL_DML_ASYNC</constant> or
78
90
<constant>PGSQL_DML_STRING</constant> combined. If <constant>PGSQL_DML_STRING</constant> is part of the
79
-
<parameter>options</parameter> then query string is returned. When <constant>PGSQL_DML_NO_CONV</constant>
91
+
<parameter>flags</parameter> then query string is returned. When <constant>PGSQL_DML_NO_CONV</constant>
80
92
or <constant>PGSQL_DML_ESCAPE</constant> is set, it does not call <function>pg_convert</function> internally.
81
93
</para>
82
94
</listitem>
...
...
@@ -89,10 +101,27 @@
89
101
&reftitle.returnvalues;
90
102
<para>
91
103
&return.success; Returns <type>string</type> if <constant>PGSQL_DML_STRING</constant> is passed
92
-
via <parameter>options</parameter>.
104
+
via <parameter>flags</parameter>.
93
105
</para>
94
106
</refsect1>
95
107

108
+
<refsect1 role="changelog">
109
+
&reftitle.changelog;
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
+
&pgsql.changelog.connection-object;
120
+
</tbody>
121
+
</tgroup>
122
+
</informaltable>
123
+
</refsect1>
124
+
96
125
<refsect1 role="examples">
97
126
&reftitle.examples;
98
127
<para>
...
...
@@ -103,8 +132,9 @@
103
132
<?php
104
133
$db = pg_connect('dbname=foo');
105
134
$data = array('field1'=>'AA', 'field2'=>'BB');
106
-
107
-
// This is safe, since $_POST is converted automatically
135
+
// This is safe somewhat, since all values are escaped.
136
+
// However PostgreSQL supports JSON/Array. These are not
137
+
// safe by neither escape nor prepared query.
108
138
$res = pg_update($db, 'post_log', $_POST, $data);
109
139
if ($res) {
110
140
echo "Data is updated: $res\n";
...
...
@@ -118,38 +148,6 @@
118
148
</para>
119
149
</refsect1>
120
150

121
-
<refsect1 role="changelog">
122
-
&reftitle.changelog;
123
-
<para>
124
-
<informaltable>
125
-
<tgroup cols="2">
126
-
<thead>
127
-
<row>
128
-
<entry>&Version;</entry>
129
-
<entry>&Description;</entry>
130
-
</row>
131
-
</thead>
132
-
<tbody>
133
-
<row>
134
-
<entry>5.6.0</entry>
135
-
<entry>
136
-
No longer experimental. Added <constant>PGSQL_DML_ESCAPE</constant> constant,
137
-
&true;/&false; and &null; data type support.
138
-
</entry>
139
-
</row>
140
-
<row>
141
-
<entry>5.5.3/5.4.19</entry>
142
-
<entry>
143
-
Direct SQL injection to <parameter>table_name</parameter> and Indirect
144
-
SQL injection to identifiers are fixed.
145
-
</entry>
146
-
</row>
147
-
</tbody>
148
-
</tgroup>
149
-
</informaltable>
150
-
</para>
151
-
</refsect1>
152
-

153
151
<refsect1 role="seealso">
154
152
&reftitle.seealso;
155
153
<para>
...
...
@@ -159,7 +157,6 @@
159
157
</para>
160
158
</refsect1>
161
159
</refentry>
162
-

163
160
<!-- Keep this comment at the end of the file
164
161
Local variables:
165
162
mode: sgml
166
163