reference/pdo/pdo/query.xml
082ddc19f53e6e254010de1a1fbbe485ff744ec1
082ddc19f53e6e254010de1a1fbbe485ff744ec1
...
...
@@ -4,63 +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
-
If more than one argument is passed to this function, the remaining arguments
61
-
will be treated as though you called
62
-
<function>PDOStatement::setFetchMode</function> on the resultant statement
63
-
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.
64
63
</para>
65
64
</note>
66
65
...
...
@@ -70,14 +69,32 @@
70
69
<para>
71
70
<variablelist>
72
71
<varlistentry>
73
-
<term><parameter>statement</parameter></term>
72
+
<term><parameter>query</parameter></term>
74
73
<listitem>
75
74
<para>
76
75
The SQL statement to prepare and execute.
77
76
</para>
78
77
<para>
79
-
Data inside the query should be <link
80
-
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.
81
98
</para>
82
99
</listitem>
83
100
</varlistentry>
...
...
@@ -87,31 +104,28 @@
87
104
<refsect1 role="returnvalues">
88
105
&reftitle.returnvalues;
89
106
<para>
90
-
<function>PDO::query</function> returns a PDOStatement object, or &false;
91
-
on failure.
107
+
Returns a <classname>PDOStatement</classname> object&return.falseforfailure;.
92
108
</para>
93
109
</refsect1>
94
110
111
+
<refsect1 role="errors">
112
+
&reftitle.errors;
113
+
&pdo.errors;
114
+
</refsect1>
115
+
95
116
<refsect1 role="examples">
96
117
&reftitle.examples;
97
118
<para>
98
119
<example>
99
-
<title>Demonstrate PDO::query</title>
100
-
<para>
101
-
A nice feature of <function>PDO::query</function> is that it
102
-
enables you to iterate over the rowset returned by a
103
-
successfully executed SELECT statement.
104
-
</para>
120
+
<title>SQL with no placeholders can be executed using <methodname>PDO::query</methodname></title>
105
121
<programlisting role="php">
106
122
<![CDATA[
107
123
<?php
108
-
function getFruit($conn) {
109
-
$sql = 'SELECT name, color, calories FROM fruit ORDER BY name';
110
-
foreach ($conn->query($sql) as $row) {
111
-
print $row['name'] . "\t";
112
-
print $row['color'] . "\t";
113
-
print $row['calories'] . "\n";
114
-
}
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";
115
129
}
116
130
?>
117
131
]]>
...
...
@@ -137,16 +151,15 @@ watermelon pink 90
137
151
&reftitle.seealso;
138
152
<para>
139
153
<simplelist>
140
-
<member><function>PDO::exec</function></member>
141
-
<member><function>PDO::prepare</function></member>
142
-
<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>
143
157
</simplelist>
144
158
</para>
145
159
</refsect1>
146
160
147
161
148
162
</refentry>
149
-
150
163
<!-- Keep this comment at the end of the file
151
164
Local variables:
152
165
mode: sgml
153
166