reference/pdo/pdo/query.xml
082ddc19f53e6e254010de1a1fbbe485ff744ec1
082ddc19f53e6e254010de1a1fbbe485ff744ec1
...
...
@@ -4,64 +4,62 @@
4
4
<refnamediv>
5
5
<refname>PDO::query</refname>
6
6
<refpurpose>
7
-
Executes an SQL statement, returning a result set as a PDOStatement object
7
+
Prepares and executes an SQL statement without placeholders
8
8
</refpurpose>
9
9
</refnamediv>
10
10
<refsect1 role="description">
11
11
&reftitle.description;
12
-
<methodsynopsis>
13
-
<modifier>public</modifier> <type>PDOStatement</type><methodname>PDO::query</methodname>
14
-
<methodparam><type>string</type><parameter>statement</parameter></methodparam>
12
+
<methodsynopsis role="PDO">
13
+
<modifier>public</modifier> <type class="union"><type>PDOStatement</type><type>false</type></type><methodname>PDO::query</methodname>
14
+
<methodparam><type>string</type><parameter>query</parameter></methodparam>
15
+
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>fetchMode</parameter><initializer>&null;</initializer></methodparam>
15
16
</methodsynopsis>
16
17
17
-
<methodsynopsis>
18
-
<modifier>public</modifier> <type>PDOStatement</type><methodname>PDO::query</methodname>
19
-
<methodparam><type>string</type><parameter>statement</parameter></methodparam>
20
-
<methodparam><type>int</type><parameter>PDO::FETCH_COLUMN</parameter></methodparam>
18
+
<methodsynopsis role="PDO">
19
+
<modifier>public</modifier> <type class="union"><type>PDOStatement</type><type>false</type></type><methodname>PDO::query</methodname>
20
+
<methodparam><type>string</type><parameter>query</parameter></methodparam>
21
+
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>fetchMode</parameter><initializer>PDO::FETCH_COLUMN</initializer></methodparam>
21
22
<methodparam><type>int</type><parameter>colno</parameter></methodparam>
22
23
</methodsynopsis>
23
24
24
-
<methodsynopsis>
25
-
<modifier>public</modifier> <type>PDOStatement</type><methodname>PDO::query</methodname>
26
-
<methodparam><type>string</type><parameter>statement</parameter></methodparam>
27
-
<methodparam><type>int</type><parameter>PDO::FETCH_CLASS</parameter></methodparam>
25
+
<methodsynopsis role="PDO">
26
+
<modifier>public</modifier> <type class="union"><type>PDOStatement</type><type>false</type></type><methodname>PDO::query</methodname>
27
+
<methodparam><type>string</type><parameter>query</parameter></methodparam>
28
+
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>fetchMode</parameter><initializer>PDO::FETCH_CLASS</initializer></methodparam>
28
29
<methodparam><type>string</type><parameter>classname</parameter></methodparam>
29
-
<methodparam><type>array</type><parameter>ctorargs</parameter></methodparam>
30
+
<methodparam><type>array</type><parameter>constructorArgs</parameter></methodparam>
30
31
</methodsynopsis>
31
32
32
-
<methodsynopsis>
33
-
<modifier>public</modifier> <type>PDOStatement</type><methodname>PDO::query</methodname>
34
-
<methodparam><type>string</type><parameter>statement</parameter></methodparam>
35
-
<methodparam><type>int</type><parameter>PDO::FETCH_INTO</parameter></methodparam>
33
+
<methodsynopsis role="PDO">
34
+
<modifier>public</modifier> <type class="union"><type>PDOStatement</type><type>false</type></type><methodname>PDO::query</methodname>
35
+
<methodparam><type>string</type><parameter>query</parameter></methodparam>
36
+
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>fetchMode</parameter><initializer>PDO::FETCH_INTO</initializer></methodparam>
36
37
<methodparam><type>object</type><parameter>object</parameter></methodparam>
37
38
</methodsynopsis>
38
39
39
40
<para>
40
-
<function>PDO::query</function> executes an SQL statement in
41
-
a single function call, returning the result set (if any) returned by the
42
-
statement as a PDOStatement object.
41
+
<methodname>PDO::query</methodname> prepares and executes an SQL statement in
42
+
a single function call, returning the statement as a <classname>PDOStatement</classname> object.
43
43
</para>
44
44
<para>
45
45
For a query that you need to issue multiple times, you will realize better
46
-
performance if you prepare a PDOStatement object using
47
-
<function>PDO::prepare</function> and issue the statement with multiple
48
-
calls to <function>PDOStatement::execute</function>.
46
+
performance if you prepare a <classname>PDOStatement</classname> object using
47
+
<methodname>PDO::prepare</methodname> and issue the statement with multiple
48
+
calls to <methodname>PDOStatement::execute</methodname>.
49
49
</para>
50
50
<para>
51
51
If you do not fetch all of the data in a result set before issuing your
52
-
next call to <function>PDO::query</function>, your call may fail. Call
53
-
<function>PDOStatement::closeCursor</function> to release the database
54
-
resources associated with the PDOStatement object before issuing your
55
-
next call to <function>PDO::query</function>.
52
+
next call to <methodname>PDO::query</methodname>, your call may fail. Call
53
+
<methodname>PDOStatement::closeCursor</methodname> to release the database
54
+
resources associated with the <classname>PDOStatement</classname> object before issuing your
55
+
next call to <methodname>PDO::query</methodname>.
56
56
</para>
57
57
58
58
<note>
59
59
<para>
60
-
Although this function is only documented as having a single
61
-
parameter, you may pass additional arguments to this function.
62
-
They will be treated as though you called
63
-
<function>PDOStatement::setFetchMode</function> on the resultant statement
64
-
object.
60
+
If the <parameter>query</parameter> contains placeholders, the statement
61
+
must be prepared and executed separately using <methodname>PDO::prepare</methodname> and
62
+
<methodname>PDOStatement::execute</methodname> methods.
65
63
</para>
66
64
</note>
67
65
...
...
@@ -71,14 +69,32 @@
71
69
<para>
72
70
<variablelist>
73
71
<varlistentry>
74
-
<term><parameter>statement</parameter></term>
72
+
<term><parameter>query</parameter></term>
75
73
<listitem>
76
74
<para>
77
75
The SQL statement to prepare and execute.
78
76
</para>
79
77
<para>
80
-
Data inside the query should be <link
81
-
linkend="pdo.quote">properly escaped</link>.
78
+
If the SQL contains placeholders, <methodname>PDO::prepare</methodname> and
79
+
<methodname>PDOStatement::execute</methodname> must be used instead.
80
+
Alternatively, the SQL can be prepared manually before calling
81
+
<methodname>PDO::query</methodname>, with the data properly formatted using
82
+
<methodname>PDO::quote</methodname> if the driver supports it.
83
+
</para>
84
+
</listitem>
85
+
</varlistentry>
86
+
<varlistentry>
87
+
<term><parameter>fetchMode</parameter></term>
88
+
<listitem>
89
+
<para>
90
+
The default fetch mode for the returned <classname>PDOStatement</classname>.
91
+
It must be one of the <link linkend="pdo.constants"><literal>PDO::FETCH_*</literal></link> constants.
92
+
</para>
93
+
<para>
94
+
If this argument is passed to the function, the remaining arguments
95
+
will be treated as though <methodname>PDOStatement::setFetchMode</methodname>
96
+
was called on the resultant statement object.
97
+
The subsequent arguments vary depending on the selected fetch mode.
82
98
</para>
83
99
</listitem>
84
100
</varlistentry>
...
...
@@ -88,31 +104,28 @@
88
104
<refsect1 role="returnvalues">
89
105
&reftitle.returnvalues;
90
106
<para>
91
-
<function>PDO::query</function> returns a PDOStatement object, or &false;
92
-
on failure.
107
+
Returns a <classname>PDOStatement</classname> object&return.falseforfailure;.
93
108
</para>
94
109
</refsect1>
95
110
111
+
<refsect1 role="errors">
112
+
&reftitle.errors;
113
+
&pdo.errors;
114
+
</refsect1>
115
+
96
116
<refsect1 role="examples">
97
117
&reftitle.examples;
98
118
<para>
99
119
<example>
100
-
<title>Demonstrate PDO::query</title>
101
-
<para>
102
-
A nice feature of <function>PDO::query</function> is that it
103
-
enables you to iterate over the rowset returned by a
104
-
successfully executed SELECT statement.
105
-
</para>
120
+
<title>SQL with no placeholders can be executed using <methodname>PDO::query</methodname></title>
106
121
<programlisting role="php">
107
122
<![CDATA[
108
123
<?php
109
-
function getFruit($conn) {
110
-
$sql = 'SELECT name, color, calories FROM fruit ORDER BY name';
111
-
foreach ($conn->query($sql) as $row) {
112
-
print $row['name'] . "\t";
113
-
print $row['color'] . "\t";
114
-
print $row['calories'] . "\n";
115
-
}
124
+
$sql = 'SELECT name, color, calories FROM fruit ORDER BY name';
125
+
foreach ($conn->query($sql) as $row) {
126
+
print $row['name'] . "\t";
127
+
print $row['color'] . "\t";
128
+
print $row['calories'] . "\n";
116
129
}
117
130
?>
118
131
]]>
...
...
@@ -138,16 +151,15 @@ watermelon pink 90
138
151
&reftitle.seealso;
139
152
<para>
140
153
<simplelist>
141
-
<member><function>PDO::exec</function></member>
142
-
<member><function>PDO::prepare</function></member>
143
-
<member><function>PDOStatement::execute</function></member>
154
+
<member><methodname>PDO::exec</methodname></member>
155
+
<member><methodname>PDO::prepare</methodname></member>
156
+
<member><methodname>PDOStatement::execute</methodname></member>
144
157
</simplelist>
145
158
</para>
146
159
</refsect1>
147
160
148
161
149
162
</refentry>
150
-
151
163
<!-- Keep this comment at the end of the file
152
164
Local variables:
153
165
mode: sgml
154
166