'[DOC-CVS] com doc/en: Improve =?UTF-8?Q?mysqli=5Freal=5Fescape=5Fstring=20docs=3A?= =?UTF-8?Q?=20ref'

[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=5Freal=5Fescape=5Fstring=20docs=3A?= =?UTF-8?Q?=20ref
From:       Christoph Michael Becker <cmb () php ! net>
Date:       2021-03-23 12:35:16
Message-ID: php-mail-b5f58eea25c18db95e421b796ee85678755664892 () git ! php ! net
[Download RAW message or body]

Commit:    df1072f8d2a3157534cb61d3734864c1f4852808
Author:    Kamil Tekiela <tekiela246@gmail.com>         Sat, 20 Mar 2021 22:43:13 \
                +0100
Committer: Christoph M. Becker <cmbecker69@gmx.de>      Tue, 23 Mar 2021 13:35:16 \
                +0100
Parents:   5f6b54fb576b7d4bc76bdd4f378595aa93f0920f
Branches:  master

Link:       http://git.php.net/?p=doc/en.git;a=commitdiff;h=df1072f8d2a3157534cb61d3734864c1f4852808


Log:
Improve mysqli_real_escape_string docs

* Tidy up the alias situation
  It should look the same as \
https://www.php.net/manual/en/function.mysqli-set-opt.php

* Add "produce" word

Copied from MySQL manual

* Removed old note

  This was changed some time back around PHP 7.3. In PHP 8 all of these warnings have \
been converted to Errors and the function doesn't return NULL or FALSE anymore.

* Revert Doc Bug #55757

  I'm sorry, but this note doesn't belong here. It is absolutely useless to point it \
out in this particular place. People migrating from mysql_* API have to do a lot more \
work than ensuring their escaping function works. This might have been added as a \
comment, but it should not be part of the official doc page.

* Provide more reasonable example

* Remove mysqli_character_set_name from See also

Closes GH-498.

Bugs:
https://bugs.php.net/55757

Changed paths:
  M  reference/mysqli/functions/mysqli-escape-string.xml
  M  reference/mysqli/mysqli/real-escape-string.xml


Diff:
diff --git a/reference/mysqli/functions/mysqli-escape-string.xml \
b/reference/mysqli/functions/mysqli-escape-string.xml index 59c358e5ef..3d42b10e0c \
                100644
--- a/reference/mysqli/functions/mysqli-escape-string.xml
+++ b/reference/mysqli/functions/mysqli-escape-string.xml
@@ -2,6 +2,7 @@
 <!-- $Revision$ -->
 <refentry xml:id="function.mysqli-escape-string" \
xmlns="http://docbook.org/ns/docbook">  <refnamediv>
+  <refname>mysqli::escape_string</refname>
   <refname>mysqli_escape_string</refname>
   <refpurpose>&Alias; <function>mysqli_real_escape_string</function></refpurpose>
  </refnamediv>
diff --git a/reference/mysqli/mysqli/real-escape-string.xml \
b/reference/mysqli/mysqli/real-escape-string.xml index bbb1d618a8..68d7c42876 100644
--- a/reference/mysqli/mysqli/real-escape-string.xml
+++ b/reference/mysqli/mysqli/real-escape-string.xml
@@ -3,7 +3,6 @@
 <refentry xml:id="mysqli.real-escape-string" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>mysqli::real_escape_string</refname>
-  <refname>mysqli::escape_string</refname>
   <refname>mysqli_real_escape_string</refname>
   <refpurpose>Escapes special characters in a string for use in an SQL statement, \
taking into account the current charset of the connection</refpurpose>  </refnamediv>
@@ -12,10 +11,6 @@
   &reftitle.description;
   <para>&style.oop;</para>
   <methodsynopsis role="oop">
-   <modifier>public</modifier> \
                <type>string</type><methodname>mysqli::escape_string</methodname>
-   <methodparam><type>string</type><parameter>string</parameter></methodparam>
-  </methodsynopsis>
-  <methodsynopsis role="oop">
    <modifier>public</modifier> \
<type>string</type><methodname>mysqli::real_escape_string</methodname>  \
<methodparam><type>string</type><parameter>string</parameter></methodparam>  \
</methodsynopsis> @@ -27,7 +22,7 @@
   </methodsynopsis>
   <para>
    This function is used to create a legal SQL string that you can use in an
-   SQL statement. The given string is encoded to an escaped SQL string,
+   SQL statement. The given string is encoded to produce an escaped SQL string,
    taking into account the current character set of the connection.
   </para>
   <caution>
@@ -69,14 +64,6 @@
    Returns an escaped string.
   </para>
  </refsect1>
- 
- <refsect1 role="errors">
-  &reftitle.errors;
-  <para>
-   Executing this function without a valid MySQLi connection passed in will
-   return &null; and emit <constant>E_WARNING</constant> level errors.
-  </para>
- </refsect1>
 
  <refsect1 role="examples">
   &reftitle.examples;
@@ -86,96 +73,60 @@
    <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->query("CREATE TEMPORARY TABLE myCity LIKE City");
 
-$city = "'s Hertogenbosch";
-
-/* this query will fail, cause we didn't escape $city */
-if (!$mysqli->query("INSERT into myCity (Name) VALUES ('$city')")) {
-    printf("Error: %s\n", $mysqli->sqlstate);
-}
+mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
+$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
 
-$city = $mysqli->real_escape_string($city);
+$city = "'s-Hertogenbosch";
 
 /* this query with escaped $city will work */
-if ($mysqli->query("INSERT into myCity (Name) VALUES ('$city')")) {
-    printf("%d Row inserted.\n", $mysqli->affected_rows);
-}
-
-$mysqli->close();
-?>
+$query = sprintf("SELECT CountryCode FROM City WHERE name='%s'",
+	$mysqli->real_escape_string($city));
+$result = $mysqli->query($query);
+printf("Select returned %d rows.\n", $result->num_rows);
+
+/* this query will fail, because we didn't escape $city */
+$query = sprintf("SELECT CountryCode FROM City WHERE name='%s'", $city);
+$result = $mysqli->query($query);
 ]]>
    </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_query($link, "CREATE TEMPORARY TABLE myCity LIKE City");
 
-$city = "'s Hertogenbosch";
+mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
+$mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");
 
-/* this query will fail, cause we didn't escape $city */
-if (!mysqli_query($link, "INSERT into myCity (Name) VALUES ('$city')")) {
-    printf("Error: %s\n", mysqli_sqlstate($link));
-}
-
-$city = mysqli_real_escape_string($link, $city);
+$city = "'s-Hertogenbosch";
 
 /* this query with escaped $city will work */
-if (mysqli_query($link, "INSERT into myCity (Name) VALUES ('$city')")) {
-    printf("%d Row inserted.\n", mysqli_affected_rows($link));
-}
-
-mysqli_close($link);
-?>
+$query = sprintf("SELECT CountryCode FROM City WHERE name='%s'",
+	mysqli_real_escape_string($mysqli, $city));
+$result = mysqli_query($mysqli, $query);
+printf("Select returned %d rows.\n", mysqli_num_rows($result));
+
+/* this query will fail, because we didn't escape $city */
+$query = sprintf("SELECT CountryCode FROM City WHERE name='%s'", $city);
+$result = mysqli_query($mysqli, $query);
 ]]>
    </programlisting>
-   &examples.outputs;
+   &examples.outputs.similar;
    <screen>
 <![CDATA[
-Error: 42000
-1 Row inserted.
+Select returned 1 rows.
+
+Fatal error: Uncaught mysqli_sql_exception: You have an error in your SQL syntax; \
check the manual that corresponds to your MySQL server version for the right syntax \
to use near 's-Hertogenbosch'' at line 1 in...  ]]>
    </screen>
   </example>
  </refsect1>
 
- <refsect1 role="notes">
-  &reftitle.notes;
-  <note>
-   <para>
-    For those accustomed to using <function>mysql_real_escape_string</function>,
-    note that the arguments of <function>mysqli_real_escape_string</function>
-    differ from what <function>mysql_real_escape_string</function> expects.
-    The <parameter>mysql</parameter> identifier comes first in 
-    <function>mysqli_real_escape_string</function>, whereas the string to be escaped
-    comes first in <function>mysql_real_escape_string</function>.
-   </para>
-  </note>
- </refsect1>
-
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
    <simplelist>
     <member><function>mysqli_set_charset</function></member>
-    <member><function>mysqli_character_set_name</function></member>
    </simplelist>
   </para>
  </refsect1>


--
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