[prev in list] [next in list] [prev in thread] [next in thread]
List: php-doc-cvs
Subject: [DOC-CVS] com doc/en: Improve =?UTF-8?Q?mysqli=5Fquery=20docs=3A=20reference/mysqli?= =?UTF-8?Q?/mys
From: Christoph Michael Becker <cmb () php ! net>
Date: 2021-03-23 12:53:28
Message-ID: php-mail-230259e8f6e8511c8411b675d9c69e62130835453 () git ! php ! net
[Download RAW message or body]
Commit: 9c9b8f3e66ec3cb9a2e638bec8d2be2b8cfc0ff2
Author: Kamil Tekiela <tekiela246@gmail.com> Mon, 22 Mar 2021 17:10:20 +0100
Committer: Christoph M. Becker <cmbecker69@gmx.de> Tue, 23 Mar 2021 13:53:28 +0100
Parents: df1072f8d2a3157534cb61d3734864c1f4852808
Branches: master
Link: http://git.php.net/?p=doc/en.git;a=commitdiff;h=9c9b8f3e66ec3cb9a2e638bec8d2be2b8cfc0ff2
Log:
Improve mysqli_query docs
* Add a nice big SQL injection warning
* Break overlong breaks
* Rewrite result_mode explanation
* Simplify examples
* Add mysqli_prepare to see also
Closes GH-497.
Changed paths:
M reference/mysqli/mysqli/query.xml
M reference/mysqli/mysqli/real-query.xml
["diff_9c9b8f3e66ec3cb9a2e638bec8d2be2b8cfc0ff2.txt" (text/plain)]
diff --git a/reference/mysqli/mysqli/query.xml b/reference/mysqli/mysqli/query.xml
index 4805db6150..3df7427eed 100644
--- a/reference/mysqli/mysqli/query.xml
+++ b/reference/mysqli/mysqli/query.xml
@@ -77,29 +77,46 @@
<para>
The query string.
</para>
- <para>
- Data inside the query should be <link \
linkend="mysqli.real-escape-string">properly escaped</link>.
- </para>
+ <warning>
+ <title>Security warning: SQL injection</title>
+ <para>
+ If the query contains any variable input then
+ <link linkend="mysqli.quickstart.prepared-statements">parameterized
+ prepared statements</link> should be used instead. Alternatively, the
+ data must be properly formatted and all strings must be escaped using
+ the <function>mysqli_real_escape_string</function>
+ function.
+ </para>
+ </warning>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>result_mode</parameter></term>
<listitem>
<para>
- Either the constant <constant>MYSQLI_USE_RESULT</constant> or
- <constant>MYSQLI_STORE_RESULT</constant> depending on the desired
- behavior. By default, <constant>MYSQLI_STORE_RESULT</constant> is used.
+ The result mode can be one of 3 constants indicating how the result will
+ be returned from the MySQL server.
+ </para>
+ <para>
+ <constant>MYSQLI_STORE_RESULT</constant> (default) - returns a
+ <classname>mysqli_result</classname> object with buffered result set.
</para>
<para>
- If you use <constant>MYSQLI_USE_RESULT</constant> all subsequent calls
- will return error <literal>Commands out of sync</literal> unless you
- call <function>mysqli_free_result</function>
+ <constant>MYSQLI_USE_RESULT</constant> - returns a
+ <classname>mysqli_result</classname> object with unbuffered result set.
+ As long as there are pending records waiting to be fetched, the
+ connection line will be busy and all subsequent calls will return error
+ <literal>Commands out of sync</literal>. To avoid the error all records
+ must be fetched from the server or the result set must be discarded by
+ calling <function>mysqli_free_result</function>.
</para>
<para>
- With <constant>MYSQLI_ASYNC</constant> (available with mysqlnd), it is
- possible to perform query asynchronously.
+ <constant>MYSQLI_ASYNC</constant> (available with mysqlnd) - the query is
+ performed asynchronously and no result set is immediately returned.
<function>mysqli_poll</function> is then used to get results from such
- queries.
+ queries. Used in combination with either
+ <constant>MYSQLI_STORE_RESULT</constant> or
+ <constant>MYSQLI_USE_RESULT</constant> constant.
</para>
</listitem>
</varlistentry>
@@ -110,9 +127,11 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
- Returns &false; on failure. For successful queries which produce a result set, \
such as <literal>SELECT, SHOW, DESCRIBE</literal> or + Returns &false; on failure. \
For successful queries which produce a result + set, such as <literal>SELECT, SHOW, \
DESCRIBE</literal> or <literal>EXPLAIN</literal>, <function>mysqli_query</function> \
will return
- a <classname>mysqli_result</classname> object. For other successful queries, \
<function>mysqli_query</function> will + a <classname>mysqli_result</classname> \
object. For other successful queries, + <function>mysqli_query</function> will
return &true;.
</para>
</refsect1>
@@ -125,90 +144,59 @@
<programlisting role="php">
<![CDATA[
<?php
-$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
-/* check connection */
-if ($mysqli->connect_errno) {
- printf("Connect failed: %s\n", $mysqli->connect_error);
- exit();
-}
+mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
+$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* Create table doesn't return a resultset */
-if ($mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City") === TRUE) {
- printf("Table myCity successfully created.\n");
-}
+$mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City");
+printf("Table myCity successfully created.\n");
/* Select queries return a resultset */
-if ($result = $mysqli->query("SELECT Name FROM City LIMIT 10")) {
- printf("Select returned %d rows.\n", $result->num_rows);
-
- /* free result set */
- $result->close();
-}
+$result = $mysqli->query("SELECT Name FROM City LIMIT 10");
+printf("Select returned %d rows.\n", $result->num_rows);
/* If we have to retrieve large amount of data we use MYSQLI_USE_RESULT */
-if ($result = $mysqli->query("SELECT * FROM City", MYSQLI_USE_RESULT)) {
-
- /* Note, that we can't execute any functions which interact with the
- server until result set was closed. All calls will return an
- 'out of sync' error */
- if (!$mysqli->query("SET @a:='this will not work'")) {
- printf("Error: %s\n", $mysqli->error);
- }
- $result->close();
-}
-
-$mysqli->close();
-?>
+$result = $mysqli->query("SELECT * FROM City", MYSQLI_USE_RESULT);
+
+/* Note, that we can't execute any functions which interact with the
+ server until all records have been fully retrieved or the result
+ set was closed. All calls will return an 'out of sync' error */
+$mysqli->query("SET @a:='this will not work'");
]]>
</programlisting>
<para>&style.procedural;</para>
<programlisting role="php">
<![CDATA[
<?php
-$link = mysqli_connect("localhost", "my_user", "my_password", "world");
-/* check connection */
-if (mysqli_connect_errno()) {
- printf("Connect failed: %s\n", mysqli_connect_error());
- exit();
-}
+mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
+$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* Create table doesn't return a resultset */
-if (mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City") === TRUE) {
- printf("Table myCity successfully created.\n");
-}
+mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City");
+printf("Table myCity successfully created.\n");
/* Select queries return a resultset */
-if ($result = mysqli_query($link, "SELECT Name FROM City LIMIT 10")) {
- printf("Select returned %d rows.\n", mysqli_num_rows($result));
-
- /* free result set */
- mysqli_free_result($result);
-}
+$result = mysqli_query($link, "SELECT Name FROM City LIMIT 10");
+printf("Select returned %d rows.\n", mysqli_num_rows($result));
/* If we have to retrieve large amount of data we use MYSQLI_USE_RESULT */
-if ($result = mysqli_query($link, "SELECT * FROM City", MYSQLI_USE_RESULT)) {
-
- /* Note, that we can't execute any functions which interact with the
- server until result set was closed. All calls will return an
- 'out of sync' error */
- if (!mysqli_query($link, "SET @a:='this will not work'")) {
- printf("Error: %s\n", mysqli_error($link));
- }
- mysqli_free_result($result);
-}
-
-mysqli_close($link);
-?>
+$result = mysqli_query($link, "SELECT * FROM City", MYSQLI_USE_RESULT);
+
+/* Note, that we can't execute any functions which interact with the
+ server until all records have been fully retrieved or the result
+ set was closed. All calls will return an 'out of sync' error */
+mysqli_query($link, "SET @a:='this will not work'");
]]>
</programlisting>
- &examples.outputs;
+ &examples.outputs.similar;
<screen>
<![CDATA[
Table myCity successfully created.
Select returned 10 rows.
-Error: Commands out of sync; You can't run this command now
+
+Fatal error: Uncaught mysqli_sql_exception: Commands out of sync; you can't run this \
command now in... ]]>
</screen>
</example>
@@ -220,6 +208,7 @@ Error: Commands out of sync; You can't run this command now
<simplelist>
<member><function>mysqli_real_query</function></member>
<member><function>mysqli_multi_query</function></member>
+ <member><function>mysqli_prepare</function></member>
<member><function>mysqli_free_result</function></member>
</simplelist>
</para>
diff --git a/reference/mysqli/mysqli/real-query.xml \
b/reference/mysqli/mysqli/real-query.xml index 59d170385d..e4e5f08fc5 100644
--- a/reference/mysqli/mysqli/real-query.xml
+++ b/reference/mysqli/mysqli/real-query.xml
@@ -40,11 +40,19 @@
<term><parameter>query</parameter></term>
<listitem>
<para>
- The query, as a string.
- </para>
- <para>
- Data inside the query should be <link \
linkend="mysqli.real-escape-string">properly escaped</link>. + The query \
string. </para>
+ <warning>
+ <title>Security warning: SQL injection</title>
+ <para>
+ If the query contains any variable input then
+ <link linkend="mysqli.quickstart.prepared-statements">parameterized
+ prepared statements</link> should be used instead. Alternatively, the
+ data must be properly formatted and all strings must be escaped using
+ the <function>mysqli_real_escape_string</function>
+ function.
+ </para>
+ </warning>
</listitem>
</varlistentry>
</variablelist>
--
PHP Documentation Commits Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic