reference/mysqli/mysqli/query.xml
d470f625f96a83d65464619297cccad7ce46e743
...
...
@@ -10,13 +10,13 @@
10
10
<refsect1 role="description">
11
11
&reftitle.description;
12
12
<para>&style.oop;</para>
13
-
<methodsynopsis role="oop">
13
+
<methodsynopsis role="mysqli">
14
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
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
-
<methodsynopsis role="procedural">
19
+
<methodsynopsis>
20
20
<type class="union"><type>mysqli_result</type><type>bool</type></type><methodname>mysqli_query</methodname>
21
21
<methodparam><type>mysqli</type><parameter>mysql</parameter></methodparam>
22
22
<methodparam><type>string</type><parameter>query</parameter></methodparam>
...
...
@@ -25,6 +25,7 @@
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,29 +78,35 @@
77
78
<para>
78
79
The query string.
79
80
</para>
80
-
<para>
81
-
Data inside the query should be <link linkend="mysqli.real-escape-string">properly escaped</link>.
82
-
</para>
83
81
</listitem>
84
82
</varlistentry>
85
83
<varlistentry>
86
84
<term><parameter>result_mode</parameter></term>
87
85
<listitem>
88
86
<para>
89
-
Either the constant <constant>MYSQLI_USE_RESULT</constant> or
90
-
<constant>MYSQLI_STORE_RESULT</constant> depending on the desired
91
-
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.
92
93
</para>
93
94
<para>
94
-
If you use <constant>MYSQLI_USE_RESULT</constant> all subsequent calls
95
-
will return error <literal>Commands out of sync</literal> unless you
96
-
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>.
97
102
</para>
98
103
<para>
99
-
With <constant>MYSQLI_ASYNC</constant> (available with mysqlnd), it is
100
-
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.
101
106
<function>mysqli_poll</function> is then used to get results from such
102
-
queries.
107
+
queries. Used in combination with either
108
+
<constant>MYSQLI_STORE_RESULT</constant> or
109
+
<constant>MYSQLI_USE_RESULT</constant> constant.
103
110
</para>
104
111
</listitem>
105
112
</varlistentry>
...
...
@@ -110,13 +117,20 @@
110
117
<refsect1 role="returnvalues">
111
118
&reftitle.returnvalues;
112
119
<para>
113
-
Returns &false; on failure. For successful queries which produce a result set, such as <literal>SELECT, SHOW, DESCRIBE</literal> or
120
+
Returns &false; on failure. For successful queries which produce a result
121
+
set, such as <literal>SELECT, SHOW, DESCRIBE</literal> or
114
122
<literal>EXPLAIN</literal>, <function>mysqli_query</function> will return
115
-
a <classname>mysqli_result</classname> object. For other successful queries, <function>mysqli_query</function> will
123
+
a <classname>mysqli_result</classname> object. For other successful queries,
124
+
<function>mysqli_query</function> will
116
125
return &true;.
117
126
</para>
118
127
</refsect1>
119
128

129
+
<refsect1 role="errors">
130
+
&reftitle.errors;
131
+
&mysqli.conditionalexception;
132
+
</refsect1>
133
+

120
134
<refsect1 role="examples">
121
135
&reftitle.examples;
122
136
<example>
...
...
@@ -125,90 +139,59 @@
125
139
<programlisting role="php">
126
140
<![CDATA[
127
141
<?php
128
-
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
129
142

130
-
/* check connection */
131
-
if ($mysqli->connect_errno) {
132
-
printf("Connect failed: %s\n", $mysqli->connect_error);
133
-
exit();
134
-
}
143
+
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
144
+
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
135
145

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

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

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

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

152
-
/* Note, that we can't execute any functions which interact with the
153
-
server until result set was closed. All calls will return an
154
-
'out of sync' error */
155
-
if (!$mysqli->query("SET @a:='this will not work'")) {
156
-
printf("Error: %s\n", $mysqli->error);
157
-
}
158
-
$result->close();
159
-
}
160
-

161
-
$mysqli->close();
162
-
?>
155
+
$result = $mysqli->query("SELECT * FROM City", MYSQLI_USE_RESULT);
156
+

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'");
163
161
]]>
164
162
</programlisting>
165
163
<para>&style.procedural;</para>
166
164
<programlisting role="php">
167
165
<![CDATA[
168
166
<?php
169
-
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
170
167

171
-
/* check connection */
172
-
if (mysqli_connect_errno()) {
173
-
printf("Connect failed: %s\n", mysqli_connect_error());
174
-
exit();
175
-
}
168
+
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
169
+
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
176
170

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

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

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

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

193
-
/* Note, that we can't execute any functions which interact with the
194
-
server until result set was closed. All calls will return an
195
-
'out of sync' error */
196
-
if (!mysqli_query($link, "SET @a:='this will not work'")) {
197
-
printf("Error: %s\n", mysqli_error($link));
198
-
}
199
-
mysqli_free_result($result);
200
-
}
201
-

202
-
mysqli_close($link);
203
-
?>
180
+
$result = mysqli_query($link, "SELECT * FROM City", MYSQLI_USE_RESULT);
181
+

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'");
204
186
]]>
205
187
</programlisting>
206
-
&examples.outputs;
188
+
&examples.outputs.similar;
207
189
<screen>
208
190
<![CDATA[
209
191
Table myCity successfully created.
210
192
Select returned 10 rows.
211
-
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...
212
195
]]>
213
196
</screen>
214
197
</example>
...
...
@@ -218,8 +201,10 @@ Error: Commands out of sync; You can't run this command now
218
201
&reftitle.seealso;
219
202
<para>
220
203
<simplelist>
204
+
<member><function>mysqli_execute_query</function></member>
221
205
<member><function>mysqli_real_query</function></member>
222
206
<member><function>mysqli_multi_query</function></member>
207
+
<member><function>mysqli_prepare</function></member>
223
208
<member><function>mysqli_free_result</function></member>
224
209
</simplelist>
225
210
</para>
226
211



Tools (French Manual)