From 59b813401500eeaee8ad7bb067c45a06c7ed1670 Mon Sep 17 00:00:00 2001
From: Philip Olson <philip@php.net>
Date: Fri, 8 Jun 2012 00:11:47 +0000
Subject: [PATCH] Documented that setting the character set via an SQL query
 will not be useful to real_escape_string. This closes PHP Bug #54605

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@326022 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../mysql/functions/mysql-real-escape-string.xml  | 15 +++++++++++++++
 reference/mysqli/mysqli/character-set-name.xml    |  1 +
 reference/mysqli/mysqli/real-escape-string.xml    | 14 ++++++++++++++
 3 files changed, 30 insertions(+)

diff --git a/reference/mysql/functions/mysql-real-escape-string.xml b/reference/mysql/functions/mysql-real-escape-string.xml
index d3270c13f5..308d4764cd 100644
--- a/reference/mysql/functions/mysql-real-escape-string.xml
+++ b/reference/mysql/functions/mysql-real-escape-string.xml
@@ -40,6 +40,20 @@
    This function must always (with few exceptions) be used to make data
    safe before sending a query to MySQL.
   </para>
+  
+  <caution>
+   <title>Security: the default character set</title>
+   <para>
+    Always set your character set at the server level, or with <function>mysql_set_charset</function>.
+   </para>
+   <para>
+    <function>mysql_real_escape_string</function> will take into account the character set
+    if it is set by either the MySQL Server (e.g., via its <literal>default-character-set</literal> directive)
+    or from <function>mysql_set_charset</function>. But, it will not use the character set that is set with
+    an SQL query, like as a <literal>SET CHARACTER SET ...</literal> or <literal>SET NAMES ...</literal> query
+    with <function>mysql_query</function>.
+   </para>
+  </caution>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -159,6 +173,7 @@ SELECT * FROM users WHERE user='aidan' AND password='' OR ''=''
   &reftitle.seealso;
   <para>
    <simplelist>
+    <member><function>mysql_set_charset</function></member>
     <member><function>mysql_client_encoding</function></member>
     <member><function>addslashes</function></member>
     <member><function>stripslashes</function></member>
diff --git a/reference/mysqli/mysqli/character-set-name.xml b/reference/mysqli/mysqli/character-set-name.xml
index 86f923e672..947071779f 100644
--- a/reference/mysqli/mysqli/character-set-name.xml
+++ b/reference/mysqli/mysqli/character-set-name.xml
@@ -98,6 +98,7 @@ Current character set is latin1_swedish_ci
   &reftitle.seealso;
   <para>
    <simplelist>
+    <member><function>mysqli_set_charset</function></member>
     <member><function>mysqli_client_encoding</function></member>
     <member><function>mysqli_real_escape_string</function></member>
    </simplelist>
diff --git a/reference/mysqli/mysqli/real-escape-string.xml b/reference/mysqli/mysqli/real-escape-string.xml
index 3c4b231199..3c5f229d4e 100644
--- a/reference/mysqli/mysqli/real-escape-string.xml
+++ b/reference/mysqli/mysqli/real-escape-string.xml
@@ -29,6 +29,19 @@
    SQL statement. The given string is encoded to an escaped SQL string,
    taking into account the current character set of the connection.
   </para>
+  <caution>
+   <title>Security: the default character set</title>
+   <para>
+    Always set your character set at the server level, or with <function>mysqli_set_charset</function>.
+   </para>
+   <para>
+    <function>mysqli_real_escape_string</function> will take into account the character set
+    if it is set by either the MySQL Server (e.g., via its <literal>default-character-set</literal> directive)
+    or from <function>mysqli_set_charset</function>. But, it will not use the character set that is set with
+    an SQL query, like as a <literal>SET CHARACTER SET ...</literal> or <literal>SET NAMES ...</literal> query
+    with <function>mysqli_query</function>.
+   </para>
+  </caution>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -155,6 +168,7 @@ Error: 42000
   &reftitle.seealso;
   <para>
    <simplelist>
+    <member><function>mysqli_set_charset</function></member>
     <member><function>mysqli_character_set_name</function></member>
    </simplelist>
   </para>