reference/pgsql/functions/pg-insert.xml
39bb8a868935a56cfce438b0169e13c02c93211c
...
...
@@ -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-insert' xmlns="http://docbook.org/ns/docbook">
4
+
<refentry xml:id="function.pg-insert" xmlns="http://docbook.org/ns/docbook">
5
5
<refnamediv>
6
6
<refname>pg_insert</refname>
7
7
<refpurpose>
...
...
@@ -12,18 +12,33 @@
12
12
<refsect1 role="description">
13
13
&reftitle.description;
14
14
<methodsynopsis>
15
-
<type>mixed</type><methodname>pg_insert</methodname>
16
-
<methodparam><type>resource</type><parameter>connection</parameter></methodparam>
15
+
<type class="union"><type>PgSql\Result</type><type>string</type><type>bool</type></type><methodname>pg_insert</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>assoc_array</parameter></methodparam>
19
-
<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 choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>PGSQL_DML_EXEC</constant></initializer></methodparam>
20
20
</methodsynopsis>
21
21
<para>
22
-
<function>pg_insert</function> inserts the values of <parameter>assoc_array</parameter>
23
-
into the table specified by <parameter>table_name</parameter>.
24
-
If <parameter>options</parameter> is
25
-
specified, <function>pg_convert</function> is applied
26
-
to <parameter>assoc_array</parameter> with the specified options.
22
+
<function>pg_insert</function> inserts the values
23
+
of <parameter>values</parameter> into the table specified
24
+
by <parameter>table_name</parameter>.
25
+
</para>
26
+
<para>
27
+
If <parameter>flags</parameter> is specified,
28
+
<function>pg_convert</function> is applied to
29
+
<parameter>values</parameter> with the specified flags.
30
+
</para>
31
+
<para>
32
+
By default <function>pg_insert</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.
27
42
</para>
28
43
</refsect1>
29
44

...
...
@@ -34,9 +49,7 @@
34
49
<varlistentry>
35
50
<term><parameter>connection</parameter></term>
36
51
<listitem>
37
-
<para>
38
-
PostgreSQL database connection resource.
39
-
</para>
52
+
&pgsql.parameter.connection;
40
53
</listitem>
41
54
</varlistentry>
42
55
<varlistentry>
...
...
@@ -44,12 +57,12 @@
44
57
<listitem>
45
58
<para>
46
59
Name of the table into which to insert rows. The table <parameter>table_name</parameter> must at least
47
-
have as many columns as <parameter>assoc_array</parameter> has elements.
60
+
have as many columns as <parameter>values</parameter> has elements.
48
61
</para>
49
62
</listitem>
50
63
</varlistentry>
51
64
<varlistentry>
52
-
<term><parameter>assoc_array</parameter></term>
65
+
<term><parameter>values</parameter></term>
53
66
<listitem>
54
67
<para>
55
68
An <type>array</type> whose keys are field names in the table <parameter>table_name</parameter>,
...
...
@@ -58,7 +71,7 @@
58
71
</listitem>
59
72
</varlistentry>
60
73
<varlistentry>
61
-
<term><parameter>options</parameter></term>
74
+
<term><parameter>flags</parameter></term>
62
75
<listitem>
63
76
<para>
64
77
Any number of <constant>PGSQL_CONV_OPTS</constant>,
...
...
@@ -67,7 +80,7 @@
67
80
<constant>PGSQL_DML_EXEC</constant>,
68
81
<constant>PGSQL_DML_ASYNC</constant> or
69
82
<constant>PGSQL_DML_STRING</constant> combined. If <constant>PGSQL_DML_STRING</constant> is part of the
70
-
<parameter>options</parameter> then query string is returned. When <constant>PGSQL_DML_NO_CONV</constant>
83
+
<parameter>flags</parameter> then query string is returned. When <constant>PGSQL_DML_NO_CONV</constant>
71
84
or <constant>PGSQL_DML_ESCAPE</constant> is set, it does not call <function>pg_convert</function> internally.
72
85
</para>
73
86
</listitem>
...
...
@@ -79,11 +92,55 @@
79
92
<refsect1 role="returnvalues">
80
93
&reftitle.returnvalues;
81
94
<para>
82
-
Returns the connection resource on success, &return.falseforfailure;. Returns <type>string</type> if <constant>PGSQL_DML_STRING</constant> is passed
83
-
via <parameter>options</parameter>.
95
+
&return.success;. Or returns a &string; on success if <constant>PGSQL_DML_STRING</constant> is passed
96
+
via <parameter>flags</parameter>.
84
97
</para>
85
98
</refsect1>
86
99

100
+
<refsect1 role="errors">
101
+
&reftitle.errors;
102
+
<para>
103
+
A <classname>ValueError</classname> is thrown when the specified table is invalid.
104
+
</para>
105
+
<para>
106
+
A <classname>ValueError</classname> or <classname>TypeError</classname> is thrown
107
+
when the value or type of field does not match properly with a PostgreSQL's type.
108
+
</para>
109
+
</refsect1>
110
+

111
+
<refsect1 role="changelog">
112
+
&reftitle.changelog;
113
+
<informaltable>
114
+
<tgroup cols="2">
115
+
<thead>
116
+
<row>
117
+
<entry>&Version;</entry>
118
+
<entry>&Description;</entry>
119
+
</row>
120
+
</thead>
121
+
<tbody>
122
+
<row>
123
+
<entry>8.3.0</entry>
124
+
<entry>
125
+
Now throws a <classname>ValueError</classname> error when the specified table is invalid;
126
+
previously an <constant>E_WARNING</constant> was emitted.
127
+
</entry>
128
+
</row>
129
+
<row>
130
+
<entry>8.3.0</entry>
131
+
<entry>
132
+
Now throws a <classname>ValueError</classname> or <classname>TypeError</classname> error
133
+
when the value or type of field does not match properly with a PostgreSQL's type;
134
+
previously an <constant>E_WARNING</constant> was emitted.
135
+
</entry>
136
+
</row>
137
+
&pgsql.changelog.return-result-object;
138
+
&pgsql.changelog.connection-object;
139
+
</tbody>
140
+
</tgroup>
141
+
</informaltable>
142
+
</refsect1>
143
+
87
144
<refsect1 role="examples">
88
145
&reftitle.examples;
89
146
<para>
...
...
@@ -93,8 +150,10 @@
93
150
<![CDATA[
94
151
<?php
95
152
$dbconn = pg_connect('dbname=foo');
96
-
// This is safe, since $_POST is converted automatically
97
-
$res = pg_insert($dbconn, 'post_log', $_POST);
153
+
// This is safe somewhat, since all values are escaped.
154
+
// However PostgreSQL supports JSON/Array. These are not
155
+
// safe by neither escape nor prepared query.
156
+
$res = pg_insert($dbconn, 'post_log', $_POST, PGSQL_DML_ESCAPE);
98
157
if ($res) {
99
158
echo "POST data is successfully logged\n";
100
159
} else {
...
...
@@ -107,45 +166,6 @@
107
166
</para>
108
167
</refsect1>
109
168

110
-
<refsect1 role="changelog">
111
-
&reftitle.changelog;
112
-
<para>
113
-
<informaltable>
114
-
<tgroup cols="2">
115
-
<thead>
116
-
<row>
117
-
<entry>&Version;</entry>
118
-
<entry>&Description;</entry>
119
-
</row>
120
-
</thead>
121
-
<tbody>
122
-
<row>
123
-
<entry>5.6.0</entry>
124
-
<entry>
125
-
Unless <constant>PGSQL_DML_STRING</constant> is passed, the function
126
-
now returns the connection resource instead of &true; on success.
127
-
</entry>
128
-
</row>
129
-
<row>
130
-
<entry>5.6.0</entry>
131
-
<entry>
132
-
No longer experimental. Added <constant>PGSQL_DML_ESCAPE</constant> constant,
133
-
&true;/&false; and &null; data type support.
134
-
</entry>
135
-
</row>
136
-
<row>
137
-
<entry>5.5.3/5.4.19</entry>
138
-
<entry>
139
-
Direct SQL injection to <parameter>table_name</parameter> and Indirect SQL
140
-
injection to identifiers are fixed.
141
-
</entry>
142
-
</row>
143
-
</tbody>
144
-
</tgroup>
145
-
</informaltable>
146
-
</para>
147
-
</refsect1>
148
-

149
169
<refsect1 role="seealso">
150
170
&reftitle.seealso;
151
171
<para>
...
...
@@ -155,7 +175,6 @@
155
175
</para>
156
176
</refsect1>
157
177
</refentry>
158
-

159
178
<!-- Keep this comment at the end of the file
160
179
Local variables:
161
180
mode: sgml
162
181



Tools (Polish Manual)