reference/mysqli/mysqli/query.xml
d470f625f96a83d65464619297cccad7ce46e743
...
...
@@ -10,21 +10,22 @@
10
10
<refsect1 role="description">
11
11
&reftitle.description;
12
12
<para>&style.oop;</para>
13
-
<methodsynopsis role="oop">
14
-
<type>mixed</type><methodname>mysqli::query</methodname>
13
+
<methodsynopsis role="mysqli">
14
+
<modifier>public</modifier> <type class="union"><type>mysqli_result</type><type>bool</type></type><methodname>mysqli::query</methodname>
15
15
<methodparam><type>string</type><parameter>query</parameter></methodparam>
16
-
<methodparam choice="opt"><type>int</type><parameter>resultmode</parameter><initializer>MYSQLI_STORE_RESULT</initializer></methodparam>
16
+
<methodparam choice="opt"><type>int</type><parameter>result_mode</parameter><initializer><constant>MYSQLI_STORE_RESULT</constant></initializer></methodparam>
17
17
</methodsynopsis>
18
18
<para>&style.procedural;</para>
19
19
<methodsynopsis>
20
-
<type>mixed</type><methodname>mysqli_query</methodname>
21
-
<methodparam><type>mysqli</type><parameter>link</parameter></methodparam>
20
+
<type class="union"><type>mysqli_result</type><type>bool</type></type><methodname>mysqli_query</methodname>
21
+
<methodparam><type>mysqli</type><parameter>mysql</parameter></methodparam>
22
22
<methodparam><type>string</type><parameter>query</parameter></methodparam>
23
-
<methodparam choice="opt"><type>int</type><parameter>resultmode</parameter><initializer>MYSQLI_STORE_RESULT</initializer></methodparam>
23
+
<methodparam choice="opt"><type>int</type><parameter>result_mode</parameter><initializer><constant>MYSQLI_STORE_RESULT</constant></initializer></methodparam>
24
24
</methodsynopsis>
25
25
<para>
26
26
Performs a <parameter>query</parameter> against the database.
27
27
</para>
28
+
&mysqli.sqlinjection.warning;
28
29
<para>
29
30
For non-DML queries (not INSERT, UPDATE or DELETE),
30
31
this function is similar to calling
...
...
@@ -34,7 +35,7 @@
34
35
</para>
35
36
<note>
36
37
<para>
37
-
In the case where you pass a statement to
38
+
In the case where a statement is passed to
38
39
<function>mysqli_query</function> that is longer than
39
40
<literal>max_allowed_packet</literal> of the server, the returned
40
41
error codes are different depending on whether you are using MySQL
...
...
@@ -77,30 +78,35 @@
77
78
<para>
78
79
The query string.
79
80
</para>
80
-
<para>
81
-
Data inside the query should be <link
82
-
linkend="mysqli.real-escape-string">properly escaped</link>.
83
-
</para>
84
81
</listitem>
85
82
</varlistentry>
86
83
<varlistentry>
87
-
<term><parameter>resultmode</parameter></term>
84
+
<term><parameter>result_mode</parameter></term>
88
85
<listitem>
89
86
<para>
90
-
Either the constant <constant>MYSQLI_USE_RESULT</constant> or
91
-
<constant>MYSQLI_STORE_RESULT</constant> depending on the desired
92
-
behavior. By default, <constant>MYSQLI_STORE_RESULT</constant> is used.
87
+
The result mode can be one of 3 constants indicating how the result will
88
+
be returned from the MySQL server.
89
+
</para>
90
+
<para>
91
+
<constant>MYSQLI_STORE_RESULT</constant> (default) - returns a
92
+
<classname>mysqli_result</classname> object with buffered result set.
93
93
</para>
94
94
<para>
95
-
If you use <constant>MYSQLI_USE_RESULT</constant> all subsequent calls
96
-
will return error <literal>Commands out of sync</literal> unless you
97
-
call <function>mysqli_free_result</function>
95
+
<constant>MYSQLI_USE_RESULT</constant> - returns a
96
+
<classname>mysqli_result</classname> object with unbuffered result set.
97
+
As long as there are pending records waiting to be fetched, the
98
+
connection line will be busy and all subsequent calls will return error
99
+
<literal>Commands out of sync</literal>. To avoid the error all records
100
+
must be fetched from the server or the result set must be discarded by
101
+
calling <function>mysqli_free_result</function>.
98
102
</para>
99
103
<para>
100
-
With <constant>MYSQLI_ASYNC</constant> (available with mysqlnd), it is
101
-
possible to perform query asynchronously.
104
+
<constant>MYSQLI_ASYNC</constant> (available with mysqlnd) - the query is
105
+
performed asynchronously and no result set is immediately returned.
102
106
<function>mysqli_poll</function> is then used to get results from such
103
-
queries.
107
+
queries. Used in combination with either
108
+
<constant>MYSQLI_STORE_RESULT</constant> or
109
+
<constant>MYSQLI_USE_RESULT</constant> constant.
104
110
</para>
105
111
</listitem>
106
112
</varlistentry>
...
...
@@ -111,35 +117,18 @@
111
117
<refsect1 role="returnvalues">
112
118
&reftitle.returnvalues;
113
119
<para>
114
-
Returns &false; on failure. For successful <literal>SELECT, SHOW, DESCRIBE</literal> or
115
-
<literal>EXPLAIN</literal> queries <function>mysqli_query</function> will return
116
-
a <classname>mysqli_result</classname> object. For other successful queries <function>mysqli_query</function> will
120
+
Returns &false; on failure. For successful queries which produce a result
121
+
set, such as <literal>SELECT, SHOW, DESCRIBE</literal> or
122
+
<literal>EXPLAIN</literal>, <function>mysqli_query</function> will return
123
+
a <classname>mysqli_result</classname> object. For other successful queries,
124
+
<function>mysqli_query</function> will
117
125
return &true;.
118
126
</para>
119
127
</refsect1>
120
128

121
-
<refsect1 role="changelog">
122
-
&reftitle.changelog;
123
-
<para>
124
-
<informaltable>
125
-
<tgroup cols="2">
126
-
<thead>
127
-
<row>
128
-
<entry>&Version;</entry>
129
-
<entry>&Description;</entry>
130
-
</row>
131
-
</thead>
132
-
<tbody>
133
-
<row>
134
-
<entry>5.3.0</entry>
135
-
<entry>
136
-
Added the ability of async queries.
137
-
</entry>
138
-
</row>
139
-
</tbody>
140
-
</tgroup>
141
-
</informaltable>
142
-
</para>
129
+
<refsect1 role="errors">
130
+
&reftitle.errors;
131
+
&mysqli.conditionalexception;
143
132
</refsect1>
144
133

145
134
<refsect1 role="examples">
...
...
@@ -150,90 +139,59 @@
150
139
<programlisting role="php">
151
140
<![CDATA[
152
141
<?php
153
-
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
154
142

155
-
/* check connection */
156
-
if ($mysqli->connect_errno) {
157
-
printf("Connect failed: %s\n", $mysqli->connect_error);
158
-
exit();
159
-
}
143
+
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
144
+
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
160
145

161
146
/* Create table doesn't return a resultset */
162
-
if ($mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City") === TRUE) {
163
-
printf("Table myCity successfully created.\n");
164
-
}
147
+
$mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City");
148
+
printf("Table myCity successfully created.\n");
165
149

166
150
/* Select queries return a resultset */
167
-
if ($result = $mysqli->query("SELECT Name FROM City LIMIT 10")) {
168
-
printf("Select returned %d rows.\n", $result->num_rows);
169
-

170
-
/* free result set */
171
-
$result->close();
172
-
}
151
+
$result = $mysqli->query("SELECT Name FROM City LIMIT 10");
152
+
printf("Select returned %d rows.\n", $result->num_rows);
173
153

174
154
/* If we have to retrieve large amount of data we use MYSQLI_USE_RESULT */
175
-
if ($result = $mysqli->query("SELECT * FROM City", MYSQLI_USE_RESULT)) {
176
-

177
-
/* Note, that we can't execute any functions which interact with the
178
-
server until result set was closed. All calls will return an
179
-
'out of sync' error */
180
-
if (!$mysqli->query("SET @a:='this will not work'")) {
181
-
printf("Error: %s\n", $mysqli->error);
182
-
}
183
-
$result->close();
184
-
}
155
+
$result = $mysqli->query("SELECT * FROM City", MYSQLI_USE_RESULT);
185
156

186
-
$mysqli->close();
187
-
?>
157
+
/* Note, that we can't execute any functions which interact with the
158
+
server until all records have been fully retrieved or the result
159
+
set was closed. All calls will return an 'out of sync' error */
160
+
$mysqli->query("SET @a:='this will not work'");
188
161
]]>
189
162
</programlisting>
190
163
<para>&style.procedural;</para>
191
164
<programlisting role="php">
192
165
<![CDATA[
193
166
<?php
194
-
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
195
167

196
-
/* check connection */
197
-
if (mysqli_connect_errno()) {
198
-
printf("Connect failed: %s\n", mysqli_connect_error());
199
-
exit();
200
-
}
168
+
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
169
+
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
201
170

202
171
/* Create table doesn't return a resultset */
203
-
if (mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City") === TRUE) {
204
-
printf("Table myCity successfully created.\n");
205
-
}
172
+
mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City");
173
+
printf("Table myCity successfully created.\n");
206
174

207
175
/* Select queries return a resultset */
208
-
if ($result = mysqli_query($link, "SELECT Name FROM City LIMIT 10")) {
209
-
printf("Select returned %d rows.\n", mysqli_num_rows($result));
210
-

211
-
/* free result set */
212
-
mysqli_free_result($result);
213
-
}
176
+
$result = mysqli_query($link, "SELECT Name FROM City LIMIT 10");
177
+
printf("Select returned %d rows.\n", mysqli_num_rows($result));
214
178

215
179
/* If we have to retrieve large amount of data we use MYSQLI_USE_RESULT */
216
-
if ($result = mysqli_query($link, "SELECT * FROM City", MYSQLI_USE_RESULT)) {
217
-

218
-
/* Note, that we can't execute any functions which interact with the
219
-
server until result set was closed. All calls will return an
220
-
'out of sync' error */
221
-
if (!mysqli_query($link, "SET @a:='this will not work'")) {
222
-
printf("Error: %s\n", mysqli_error($link));
223
-
}
224
-
mysqli_free_result($result);
225
-
}
180
+
$result = mysqli_query($link, "SELECT * FROM City", MYSQLI_USE_RESULT);
226
181

227
-
mysqli_close($link);
228
-
?>
182
+
/* Note, that we can't execute any functions which interact with the
183
+
server until all records have been fully retrieved or the result
184
+
set was closed. All calls will return an 'out of sync' error */
185
+
mysqli_query($link, "SET @a:='this will not work'");
229
186
]]>
230
187
</programlisting>
231
-
&examples.outputs;
188
+
&examples.outputs.similar;
232
189
<screen>
233
190
<![CDATA[
234
191
Table myCity successfully created.
235
192
Select returned 10 rows.
236
-
Error: Commands out of sync; You can't run this command now
193
+

194
+
Fatal error: Uncaught mysqli_sql_exception: Commands out of sync; you can't run this command now in...
237
195
]]>
238
196
</screen>
239
197
</example>
...
...
@@ -243,15 +201,16 @@ Error: Commands out of sync; You can't run this command now
243
201
&reftitle.seealso;
244
202
<para>
245
203
<simplelist>
204
+
<member><function>mysqli_execute_query</function></member>
246
205
<member><function>mysqli_real_query</function></member>
247
206
<member><function>mysqli_multi_query</function></member>
207
+
<member><function>mysqli_prepare</function></member>
248
208
<member><function>mysqli_free_result</function></member>
249
209
</simplelist>
250
210
</para>
251
211
</refsect1>
252
212

253
213
</refentry>
254
-

255
214
<!-- Keep this comment at the end of the file
256
215
Local variables:
257
216
mode: sgml
258
217



Tools (Chinese (Simplified) Manual)