php-doc-en/reference/mysqli/functions/mysqli-real-escape-string.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.15 $ -->
<refentry xml:id="function.mysqli-real-escape-string" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>mysqli_real_escape_string</refname>
  <refname>mysqli->real_escape_string()</refname>
  <refpurpose>Escapes special characters in a string for use in a SQL statement, taking into account the current charset of the connection</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <para>Procedural style:</para>
  <methodsynopsis>
   <type>string</type><methodname>mysqli_real_escape_string</methodname>
   <methodparam><type>mysqli</type><parameter>link</parameter></methodparam>
   <methodparam><type>string</type><parameter>escapestr</parameter></methodparam>
  </methodsynopsis>
  <para>Object oriented style (both methods are equivalent):</para>
  <classsynopsis>
   <ooclass><classname>mysqli</classname></ooclass>
   <methodsynopsis>
    <type>string</type><methodname>escape_string</methodname>
    <methodparam><type>string</type><parameter>escapestr</parameter></methodparam>
   </methodsynopsis>
    <methodsynopsis>
    <type>string</type><methodname>real_escape_string</methodname>
    <methodparam><type>string</type><parameter>escapestr</parameter></methodparam>
   </methodsynopsis>
  </classsynopsis>
  <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,
   taking into account the current character set of the connection.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    &mysqli.link.description;
    <varlistentry>
     <term><parameter>escapestr</parameter></term>
     <listitem>
      <para>
       The string to be escaped.
      </para>
      <para>
       Characters encoded are <literal>NUL (ASCII 0), \n, \r, \, ', ", and
       Control-Z</literal>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns an escaped string.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title>Object oriented style</title>
   <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);
}

$city = $mysqli->real_escape_string($city);

/* 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();
?>
]]>
  </programlisting>
  </example>
  <example>
   <title>Procedural style</title>
   <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";

/* 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);

/* 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);
?>
]]>
   </programlisting>
  </example>
  &example.outputs;
  <screen>
<![CDATA[
Error: 42000
1 Row inserted.
]]>
  </screen>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>mysqli_character_set_name</function></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->