<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mysqli.real-connect.html">mysqli::real_connect</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mysqli.real-query.html">mysqli::real_query</a></div>
<div class="up"><a href="class.mysqli.html">mysqli</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mysqli.real-escape-string" class="refentry">
<div class="refnamediv">
<h1 class="refname">mysqli::real_escape_string</h1>
<h1 class="refname">mysqli_real_escape_string</h1>
<p class="verinfo">(PHP 5)</p><p class="refpurpose"><span class="refname">mysqli::real_escape_string</span> -- <span class="refname">mysqli_real_escape_string</span> — <span class="dc-title">Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection</span></p>
</div>
<div class="refsect1 description" id="refsect1-mysqli.real-escape-string-description">
<h3 class="title">Description</h3>
<p class="para">Object oriented style</p>
<div class="methodsynopsis dc-description">
<span class="type">string</span> <span class="methodname"><a href="function.mysqli-escape-string.html" class="methodname">mysqli::escape_string</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$escapestr</code></span>
)</div>
<div class="methodsynopsis dc-description">
<span class="type">string</span> <span class="methodname"><strong>mysqli::real_escape_string</strong></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$escapestr</code></span>
)</div>
<p class="para rdfs-comment">Procedural style</p>
<div class="methodsynopsis dc-description">
<span class="type">string</span> <span class="methodname"><strong>mysqli_real_escape_string</strong></span>
( <span class="methodparam"><span class="type"><a href="class.mysqli.html" class="type mysqli">mysqli</a></span> <code class="parameter">$link</code></span>
, <span class="methodparam"><span class="type">string</span> <code class="parameter">$escapestr</code></span>
)</div>
<p class="para rdfs-comment">
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.
</p>
<div class="caution"><strong class="caution">Caution</strong>
<h1 class="title">Security: the default character set</h1>
<p class="para">
The character set must be set either at the server level, or with
the API function <span class="function"><a href="mysqli.set-charset.html" class="function">mysqli_set_charset()</a></span> for it to affect
<span class="function"><strong>mysqli_real_escape_string()</strong></span>. See the concepts section
on <a href="mysqlinfo.concepts.charset.html" class="link">character sets</a> for
more information.
</p>
</div>
</div>
<div class="refsect1 parameters" id="refsect1-mysqli.real-escape-string-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">
link</code></em></span><dd>
<p class="para">Procedural style only: A link identifier
returned by <span class="function"><a href="function.mysqli-connect.html" class="function">mysqli_connect()</a></span> or <span class="function"><a href="mysqli.init.html" class="function">mysqli_init()</a></span>
</p></dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">escapestr</code></em></span>
<dd>
<p class="para">
The string to be escaped.
</p>
<p class="para">
Characters encoded are <em>NUL (ASCII 0), \n, \r, \, ', ", and
Control-Z</em>.
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-mysqli.real-escape-string-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns an escaped string.
</p>
</div>
<div class="refsect1 examples" id="refsect1-mysqli.real-escape-string-examples">
<h3 class="title">Examples</h3>
<div class="example" id="example-1680">
<p><strong>Example #1 <span class="methodname"><strong>mysqli::real_escape_string()</strong></span> example</strong></p>
<div class="example-contents"><p>Object oriented style</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$mysqli </span><span style="color: #007700">= new </span><span style="color: #0000BB">mysqli</span><span style="color: #007700">(</span><span style="color: #DD0000">"localhost"</span><span style="color: #007700">, </span><span style="color: #DD0000">"my_user"</span><span style="color: #007700">, </span><span style="color: #DD0000">"my_password"</span><span style="color: #007700">, </span><span style="color: #DD0000">"world"</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">/* check connection */<br /></span><span style="color: #007700">if (</span><span style="color: #0000BB">mysqli_connect_errno</span><span style="color: #007700">()) {<br /> </span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"Connect failed: %s\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">mysqli_connect_error</span><span style="color: #007700">());<br /> exit();<br />}<br /><br /></span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">query</span><span style="color: #007700">(</span><span style="color: #DD0000">"CREATE TEMPORARY TABLE myCity LIKE City"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$city </span><span style="color: #007700">= </span><span style="color: #DD0000">"'s Hertogenbosch"</span><span style="color: #007700">;<br /><br /></span><span style="color: #FF8000">/* this query will fail, cause we didn't escape $city */<br /></span><span style="color: #007700">if (!</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">query</span><span style="color: #007700">(</span><span style="color: #DD0000">"INSERT into myCity (Name) VALUES ('</span><span style="color: #0000BB">$city</span><span style="color: #DD0000">')"</span><span style="color: #007700">)) {<br /> </span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"Error: %s\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">sqlstate</span><span style="color: #007700">);<br />}<br /><br /></span><span style="color: #0000BB">$city </span><span style="color: #007700">= </span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">real_escape_string</span><span style="color: #007700">(</span><span style="color: #0000BB">$city</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">/* this query with escaped $city will work */<br /></span><span style="color: #007700">if (</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">query</span><span style="color: #007700">(</span><span style="color: #DD0000">"INSERT into myCity (Name) VALUES ('</span><span style="color: #0000BB">$city</span><span style="color: #DD0000">')"</span><span style="color: #007700">)) {<br /> </span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"%d Row inserted.\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">affected_rows</span><span style="color: #007700">);<br />}<br /><br /></span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">close</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>Procedural style</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$link </span><span style="color: #007700">= </span><span style="color: #0000BB">mysqli_connect</span><span style="color: #007700">(</span><span style="color: #DD0000">"localhost"</span><span style="color: #007700">, </span><span style="color: #DD0000">"my_user"</span><span style="color: #007700">, </span><span style="color: #DD0000">"my_password"</span><span style="color: #007700">, </span><span style="color: #DD0000">"world"</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">/* check connection */<br /></span><span style="color: #007700">if (</span><span style="color: #0000BB">mysqli_connect_errno</span><span style="color: #007700">()) {<br /> </span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"Connect failed: %s\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">mysqli_connect_error</span><span style="color: #007700">());<br /> exit();<br />}<br /><br /></span><span style="color: #0000BB">mysqli_query</span><span style="color: #007700">(</span><span style="color: #0000BB">$link</span><span style="color: #007700">, </span><span style="color: #DD0000">"CREATE TEMPORARY TABLE myCity LIKE City"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$city </span><span style="color: #007700">= </span><span style="color: #DD0000">"'s Hertogenbosch"</span><span style="color: #007700">;<br /><br /></span><span style="color: #FF8000">/* this query will fail, cause we didn't escape $city */<br /></span><span style="color: #007700">if (!</span><span style="color: #0000BB">mysqli_query</span><span style="color: #007700">(</span><span style="color: #0000BB">$link</span><span style="color: #007700">, </span><span style="color: #DD0000">"INSERT into myCity (Name) VALUES ('</span><span style="color: #0000BB">$city</span><span style="color: #DD0000">')"</span><span style="color: #007700">)) {<br /> </span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"Error: %s\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">mysqli_sqlstate</span><span style="color: #007700">(</span><span style="color: #0000BB">$link</span><span style="color: #007700">));<br />}<br /><br /></span><span style="color: #0000BB">$city </span><span style="color: #007700">= </span><span style="color: #0000BB">mysqli_real_escape_string</span><span style="color: #007700">(</span><span style="color: #0000BB">$link</span><span style="color: #007700">, </span><span style="color: #0000BB">$city</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">/* this query with escaped $city will work */<br /></span><span style="color: #007700">if (</span><span style="color: #0000BB">mysqli_query</span><span style="color: #007700">(</span><span style="color: #0000BB">$link</span><span style="color: #007700">, </span><span style="color: #DD0000">"INSERT into myCity (Name) VALUES ('</span><span style="color: #0000BB">$city</span><span style="color: #DD0000">')"</span><span style="color: #007700">)) {<br /> </span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"%d Row inserted.\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">mysqli_affected_rows</span><span style="color: #007700">(</span><span style="color: #0000BB">$link</span><span style="color: #007700">));<br />}<br /><br /></span><span style="color: #0000BB">mysqli_close</span><span style="color: #007700">(</span><span style="color: #0000BB">$link</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above examples will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
Error: 42000
1 Row inserted.
</pre></div>
</div>
</div>
</div>
<div class="refsect1 notes" id="refsect1-mysqli.real-escape-string-notes">
<h3 class="title">Notes</h3>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
For those accustomed to using <span class="function"><a href="function.mysql-real-escape-string.html" class="function">mysql_real_escape_string()</a></span>,
note that the arguments of <span class="function"><strong>mysqli_real_escape_string()</strong></span>
differ from what <span class="function"><a href="function.mysql-real-escape-string.html" class="function">mysql_real_escape_string()</a></span> expects.
The <em><code class="parameter">link</code></em> identifier comes first in
<span class="function"><strong>mysqli_real_escape_string()</strong></span>, whereas the string to be escaped
comes first in <span class="function"><a href="function.mysql-real-escape-string.html" class="function">mysql_real_escape_string()</a></span>.
</p>
</p></blockquote>
</div>
<div class="refsect1 seealso" id="refsect1-mysqli.real-escape-string-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="function"><a href="mysqli.set-charset.html" class="function" rel="rdfs-seeAlso">mysqli_set_charset()</a> - Sets the default client character set</span></li>
<li class="member"> <span class="function"><a href="mysqli.character-set-name.html" class="function" rel="rdfs-seeAlso">mysqli_character_set_name()</a> - Returns the default character set for the database connection</span></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mysqli.real-connect.html">mysqli::real_connect</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mysqli.real-query.html">mysqli::real_query</a></div>
<div class="up"><a href="class.mysqli.html">mysqli</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
