1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry xml:id="function.pg-query-params" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>pg_query_params</refname>
<refpurpose>Submits a command to the server and waits for the result, with the ability to pass parameters separately from the SQL command text</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type class="union"><type>PgSql\Result</type><type>false</type></type><methodname>pg_query_params</methodname>
<methodparam choice="opt"><type>PgSql\Connection</type><parameter>connection</parameter></methodparam>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
<methodparam><type>array</type><parameter>params</parameter></methodparam>
</methodsynopsis>
<para>
Submits a command to the server and waits for the result, with the ability
to pass parameters separately from the SQL command text.
</para>
<para>
<function>pg_query_params</function> is like <function>pg_query</function>,
but offers additional functionality: parameter
values can be specified separately from the command string proper.
<function>pg_query_params</function> is supported only against PostgreSQL 7.4 or
higher connections; it will fail when using earlier versions.
</para>
<para>
If parameters are used, they are referred to in the
<parameter>query</parameter> string as $1, $2, etc. The same parameter may
appear more than once in the <parameter>query</parameter>; the same value
will be used in that case. <parameter>params</parameter> specifies the
actual values of the parameters. A &null; value in this array means the
corresponding parameter is SQL <literal>NULL</literal>.
</para>
<para>
The primary advantage of <function>pg_query_params</function> over <function>pg_query</function>
is that parameter values
may be separated from the <parameter>query</parameter> string, thus avoiding the need for tedious
and error-prone quoting and escaping. Unlike <function>pg_query</function>,
<function>pg_query_params</function> allows at
most one SQL command in the given string. (There can be semicolons in it,
but not more than one nonempty command.)
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>connection</parameter></term>
<listitem>
&pgsql.parameter.connection-with-unspecified-default;
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>query</parameter></term>
<listitem>
<para>
The parameterized SQL statement. Must contain only a single statement.
(multiple statements separated by semi-colons are not allowed.) If any parameters
are used, they are referred to as $1, $2, etc.
</para>
<para>
User-supplied values should always be passed as parameters, not
interpolated into the query string, where they form possible
<link linkend="security.database.sql-injection"> SQL injection</link>
attack vectors and introduce bugs when handling data containing quotes.
If for some reason you cannot use a parameter, ensure that interpolated
values are <link linkend="function.pg-escape-string">properly escaped</link>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>params</parameter></term>
<listitem>
<para>
An array of parameter values to substitute for the $1, $2, etc. placeholders
in the original prepared query string. The number of elements in the array
must match the number of placeholders.
</para>
<para>
Values intended for <literal>bytea</literal> fields are not supported as
parameters. Use <function>pg_escape_bytea</function> instead, or use the
large object functions.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
An <classname>PgSql\Result</classname> instance on success, &return.falseforfailure;.
</para>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
&pgsql.changelog.return-result-object;
&pgsql.changelog.connection-object;
</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Using <function>pg_query_params</function></title>
<programlisting role="php">
<![CDATA[
<?php
// Connect to a database named "mary"
$dbconn = pg_connect("dbname=mary");
// Find all shops named Joe's Widgets. Note that it is not necessary to
// escape "Joe's Widgets"
$result = pg_query_params($dbconn, 'SELECT * FROM shops WHERE name = $1', array("Joe's Widgets"));
// Compare against just using pg_query
$str = pg_escape_string("Joe's Widgets");
$result = pg_query($dbconn, "SELECT * FROM shops WHERE name = '{$str}'");
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>pg_query</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
|
