reference/pgsql/functions/pg-select.xml
2fa74a5512c0a7d3eabe39b1060646fc32f253f5
2fa74a5512c0a7d3eabe39b1060646fc32f253f5
...
...
@@ -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-select' xmlns="http://docbook.org/ns/docbook">
4
+
<refentry xml:id="function.pg-select" xmlns="http://docbook.org/ns/docbook">
5
5
<refnamediv>
6
6
<refname>pg_select</refname>
7
7
<refpurpose>
...
...
@@ -12,66 +12,99 @@
12
12
<refsect1 role="description">
13
13
&reftitle.description;
14
14
<methodsynopsis>
15
-
<type>mixed</type><methodname>pg_select</methodname>
16
-
<methodparam><type>resource</type><parameter>connection</parameter></methodparam>
15
+
<type class="union"><type>array</type><type>string</type><type>false</type></type><methodname>pg_select</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>conditions</parameter></methodparam>
19
+
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>PGSQL_DML_EXEC</constant></initializer></methodparam>
20
+
<methodparam choice="opt"><type>int</type><parameter>mode</parameter><initializer><constant>PGSQL_ASSOC</constant></initializer></methodparam>
20
21
</methodsynopsis>
21
22
<para>
22
23
<function>pg_select</function> selects records specified by
23
-
<literal>assoc_array</literal> which has
24
-
<literal>field=>value</literal>. For a successful query, it returns an
24
+
<parameter>conditions</parameter> which has
25
+
<literal>field=>value</literal>. For a successful query, it returns an
25
26
array containing all records and fields that match the condition
26
-
specified by <literal>assoc_array</literal>.
27
+
specified by <parameter>conditions</parameter>.
27
28
</para>
28
-
<para>If <literal>options</literal> is specified,
29
+
<para>
30
+
If <parameter>flags</parameter> is set,
29
31
<function>pg_convert</function> is applied to
30
-
<literal>assoc_array</literal> with the specified flags.
32
+
<parameter>conditions</parameter> with the specified flags.
33
+
</para>
34
+
<para>
35
+
If <parameter>mode</parameter> is set,
36
+
the return value will be in the form of an array
37
+
with <constant>PGSQL_NUM</constant>, an associative array
38
+
with <constant>PGSQL_ASSOC</constant> (default) or both
39
+
with <constant>PGSQL_BOTH</constant>.
40
+
</para>
41
+
<para>
42
+
By default <function>pg_select</function> passes raw values. Values
43
+
must be escaped or PGSQL_DML_ESCAPE option must be
44
+
specified. PGSQL_DML_ESCAPE quotes and escapes
45
+
parameters/identifiers. Therefore, table/column names became case
46
+
sensitive.
47
+
</para>
48
+
<para>
49
+
Note that neither escape nor prepared query can protect LIKE query,
50
+
JSON, Array, Regex, etc. These parameters should be handled
51
+
according to their contexts. i.e. Escape/validate values.
31
52
</para>
32
53
</refsect1>
33
54
34
-
<refsect1 role="parameters">
35
-
&reftitle.parameters;
36
-
<para>
37
-
<variablelist>
38
-
<varlistentry>
39
-
<term><parameter>connection</parameter></term>
40
-
<listitem>
41
-
<para>
42
-
PostgreSQL database connection resource.
43
-
</para>
44
-
</listitem>
45
-
</varlistentry>
46
-
<varlistentry>
47
-
<term><parameter>table_name</parameter></term>
48
-
<listitem>
49
-
<para>
50
-
Name of the table from which to select rows.
51
-
</para>
52
-
</listitem>
53
-
</varlistentry>
54
-
<varlistentry>
55
-
<term><parameter>assoc_array</parameter></term>
56
-
<listitem>
57
-
<para>
58
-
An <type>array</type> whose keys are field names in the table <parameter>table_name</parameter>,
59
-
and whose values are the conditions that a row must meet to be retrieved.
60
-
</para>
61
-
</listitem>
62
-
</varlistentry>
63
-
<varlistentry>
64
-
<term><parameter>options</parameter></term>
65
-
<listitem>
66
-
<para>
67
-
Any number of <constant>PGSQL_CONV_FORCE_NULL</constant>,
68
-
<constant>PGSQL_DML_NO_CONV</constant>,
69
-
<constant>PGSQL_DML_ESCAPE</constant>,
70
-
<constant>PGSQL_DML_EXEC</constant>,
71
-
<constant>PGSQL_DML_ASYNC</constant> or
72
-
<constant>PGSQL_DML_STRING</constant> combined. If <constant>PGSQL_DML_STRING</constant> is part of the
73
-
<parameter>options</parameter> then query string is returned. When <constant>PGSQL_DML_NO_CONV</constant>
74
-
or <constant>PGSQL_DML_ESCAPE</constant> is set, it does not call <function>pg_convert</function> internally.
55
+
<refsect1 role="parameters">
56
+
&reftitle.parameters;
57
+
<para>
58
+
<variablelist>
59
+
<varlistentry>
60
+
<term><parameter>connection</parameter></term>
61
+
<listitem>
62
+
&pgsql.parameter.connection;
63
+
</listitem>
64
+
</varlistentry>
65
+
<varlistentry>
66
+
<term><parameter>table_name</parameter></term>
67
+
<listitem>
68
+
<para>
69
+
Name of the table from which to select rows.
70
+
</para>
71
+
</listitem>
72
+
</varlistentry>
73
+
<varlistentry>
74
+
<term><parameter>conditions</parameter></term>
75
+
<listitem>
76
+
<para>
77
+
An <type>array</type> whose keys are field names in the table <parameter>table_name</parameter>,
78
+
and whose values are the conditions that a row must meet to be retrieved.
79
+
</para>
80
+
</listitem>
81
+
</varlistentry>
82
+
<varlistentry>
83
+
<term><parameter>flags</parameter></term>
84
+
<listitem>
85
+
<para>
86
+
Any number of <constant>PGSQL_CONV_FORCE_NULL</constant>,
87
+
<constant>PGSQL_DML_NO_CONV</constant>,
88
+
<constant>PGSQL_DML_ESCAPE</constant>,
89
+
<constant>PGSQL_DML_EXEC</constant>,
90
+
<constant>PGSQL_DML_ASYNC</constant> or
91
+
<constant>PGSQL_DML_STRING</constant> combined. If <constant>PGSQL_DML_STRING</constant> is part of the
92
+
<parameter>flags</parameter> then the query string is returned. When <constant>PGSQL_DML_NO_CONV</constant>
93
+
or <constant>PGSQL_DML_ESCAPE</constant> is set, it does not call <function>pg_convert</function> internally.
94
+
</para>
95
+
</listitem>
96
+
</varlistentry>
97
+
<varlistentry>
98
+
<term><parameter>mode</parameter></term>
99
+
<listitem>
100
+
<para>
101
+
Any number of <constant>PGSQL_ASSOC</constant>,
102
+
<constant>PGSQL_NUM</constant> or
103
+
<constant>PGSQL_BOTH</constant>
104
+
If <constant>PGSQL_ASSOC</constant> is set the return value will be an associative <type>array</type>,
105
+
with <constant>PGSQL_NUM</constant> the return value will be an <type>array</type>, and
106
+
with <constant>PGSQL_BOTH</constant> the return value will be both an associative and
107
+
numerically indexed <type>array</type>.
75
108
</para>
76
109
</listitem>
77
110
</varlistentry>
...
...
@@ -82,32 +115,8 @@
82
115
<refsect1 role="returnvalues">
83
116
&reftitle.returnvalues;
84
117
<para>
85
-
&return.success; Returns <type>string</type> if <constant>PGSQL_DML_STRING</constant> is passed
86
-
via <parameter>options</parameter>.
87
-
</para>
88
-
</refsect1>
89
-
90
-
<refsect1 role="examples">
91
-
&reftitle.examples;
92
-
<para>
93
-
<example>
94
-
<title><function>pg_select</function> example</title>
95
-
<programlisting role="php">
96
-
<![CDATA[
97
-
<?php
98
-
$db = pg_connect('dbname=foo');
99
-
// This is safe, since $_POST is converted automatically
100
-
$rec = pg_select($db, 'post_log', $_POST);
101
-
if ($rec) {
102
-
echo "Records selected\n";
103
-
var_dump($rec);
104
-
} else {
105
-
echo "User must have sent wrong inputs\n";
106
-
}
107
-
?>
108
-
]]>
109
-
</programlisting>
110
-
</example>
118
+
Returns <type>string</type> if <constant>PGSQL_DML_STRING</constant> is passed
119
+
via <parameter>flags</parameter>, otherwise it returns an <type>array</type> on success, &return.falseforfailure;.
111
120
</para>
112
121
</refsect1>
113
122
...
...
@@ -123,18 +132,11 @@
123
132
</row>
124
133
</thead>
125
134
<tbody>
135
+
&pgsql.changelog.connection-object;
126
136
<row>
127
-
<entry>5.6.0</entry>
128
-
<entry>
129
-
No longer experimental. Added <constant>PGSQL_DML_ESCAPE</constant> constant,
130
-
&true;/&false; and &null; data type support.
131
-
</entry>
132
-
</row>
133
-
<row>
134
-
<entry>5.5.3/5.4.19</entry>
137
+
<entry>7.1.0</entry>
135
138
<entry>
136
-
Direct SQL injection to <parameter>table_name</parameter> and Indirect SQL
137
-
injection to identifiers are fixed.
139
+
The <parameter>mode</parameter> parameter was added.
138
140
</entry>
139
141
</row>
140
142
</tbody>
...
...
@@ -143,6 +145,32 @@
143
145
</para>
144
146
</refsect1>
145
147
148
+
<refsect1 role="examples">
149
+
&reftitle.examples;
150
+
<para>
151
+
<example>
152
+
<title><function>pg_select</function> example</title>
153
+
<programlisting role="php">
154
+
<![CDATA[
155
+
<?php
156
+
$db = pg_connect('dbname=foo');
157
+
// This is safe somewhat, since all values are escaped.
158
+
// However PostgreSQL supports JSON/Array. These are not
159
+
// safe by neither escape nor prepared query.
160
+
$rec = pg_select($db, 'post_log', $_POST, PG_DML_ESCAPE);
161
+
if ($rec) {
162
+
echo "Records selected\n";
163
+
var_dump($rec);
164
+
} else {
165
+
echo "User must have sent wrong inputs\n";
166
+
}
167
+
?>
168
+
]]>
169
+
</programlisting>
170
+
</example>
171
+
</para>
172
+
</refsect1>
173
+
146
174
<refsect1 role="seealso">
147
175
&reftitle.seealso;
148
176
<para>
...
...
@@ -152,7 +180,6 @@
152
180
</para>
153
181
</refsect1>
154
182
</refentry>
155
-
156
183
<!-- Keep this comment at the end of the file
157
184
Local variables:
158
185
mode: sgml
159
186