<!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>Convert special characters to HTML entities</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.htmlspecialchars-decode.html">htmlspecialchars_decode</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.implode.html">implode</a></div>
<div class="up"><a href="ref.strings.html">String Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.htmlspecialchars" class="refentry">
<div class="refnamediv">
<h1 class="refname">htmlspecialchars</h1>
<p class="verinfo">(PHP 4, PHP 5)</p><p class="refpurpose"><span class="refname">htmlspecialchars</span> — <span class="dc-title">Convert special characters to HTML entities</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.htmlspecialchars-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type">string</span> <span class="methodname"><strong>htmlspecialchars</strong></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$string</code></span>
[, <span class="methodparam"><span class="type">int</span> <code class="parameter">$flags</code><span class="initializer"> = ENT_COMPAT | ENT_HTML401</span></span>
[, <span class="methodparam"><span class="type">string</span> <code class="parameter">$encoding</code><span class="initializer"> = 'UTF-8'</span></span>
[, <span class="methodparam"><span class="type">bool</span> <code class="parameter">$double_encode</code><span class="initializer"> = true</span></span>
]]] )</div>
<p class="para rdfs-comment">
Certain characters have special significance in HTML, and should
be represented by HTML entities if they are to preserve their
meanings. This function returns a string with these
conversions made. If you require all input substrings that have associated
named entities to be translated, use <span class="function"><a href="function.htmlentities.html" class="function">htmlentities()</a></span>
instead.
</p>
<p class="para">
If the input string passed to this function and the final document share the
same character set, this function is sufficient to prepare input for
inclusion in most contexts of an HTML document. If, however, the input can
represent characters that are not coded in the final document character set
and you wish to retain those characters (as numeric or named entities),
both this function and <span class="function"><a href="function.htmlentities.html" class="function">htmlentities()</a></span> (which only encodes
substrings that have named entity equivalents) may be insufficient.
You may have to use <span class="function"><a href="function.mb-encode-numericentity.html" class="function">mb_encode_numericentity()</a></span> instead.
</p>
<p class="para">
The translations performed are:
<ul class="itemizedlist">
<li class="listitem">
<span class="simpara">
'&' (ampersand) becomes '&amp;'
</span>
</li>
<li class="listitem">
<span class="simpara">
'"' (double quote) becomes '&quot;' when <strong><code>ENT_NOQUOTES</code></strong>
is not set.
</span>
</li>
<li class="listitem">
<span class="simpara">
"'" (single quote) becomes '&#039;' (or &apos;)
only when <strong><code>ENT_QUOTES</code></strong> is set.
</span>
</li>
<li class="listitem">
<span class="simpara">
'<' (less than) becomes '&lt;'
</span>
</li>
<li class="listitem">
<span class="simpara">
'>' (greater than) becomes '&gt;'
</span>
</li>
</ul>
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.htmlspecialchars-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">string</code></em></span>
<dd>
<p class="para">
The <span class="type"><a href="language.types.string.html" class="type string">string</a></span> being converted.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">flags</code></em></span>
<dd>
<p class="para">
A bitmask of one or more of the following flags, which specify how to handle quotes,
invalid code unit sequences and the used document type. The default is
<em>ENT_COMPAT | ENT_HTML401</em>.
<table class="doctable table">
<caption><strong>Available <em><code class="parameter">flags</code></em> constants</strong></caption>
<thead>
<tr>
<th>Constant Name</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td><strong><code>ENT_COMPAT</code></strong></td>
<td>Will convert double-quotes and leave single-quotes alone.</td>
</tr>
<tr>
<td><strong><code>ENT_QUOTES</code></strong></td>
<td>Will convert both double and single quotes.</td>
</tr>
<tr>
<td><strong><code>ENT_NOQUOTES</code></strong></td>
<td>Will leave both double and single quotes unconverted.</td>
</tr>
<tr>
<td><strong><code>ENT_IGNORE</code></strong></td>
<td>
Silently discard invalid code unit sequences instead of returning
an empty string. Using this flag is discouraged as it
<a href="http://unicode.org/reports/tr36/#Deletion_of_Noncharacters" class="link external">» may have security implications</a>.
</td>
</tr>
<tr>
<td><strong><code>ENT_SUBSTITUTE</code></strong></td>
<td>
Replace invalid code unit sequences with a Unicode Replacement Character
U+FFFD (UTF-8) or &#FFFD; (otherwise) instead of returning an empty string.
</td>
</tr>
<tr>
<td><strong><code>ENT_DISALLOWED</code></strong></td>
<td>
Replace invalid code points for the given document type with a
Unicode Replacement Character U+FFFD (UTF-8) or &#FFFD;
(otherwise) instead of leaving them as is. This may be useful, for
instance, to ensure the well-formedness of XML documents with
embedded external content.
</td>
</tr>
<tr>
<td><strong><code>ENT_HTML401</code></strong></td>
<td>
Handle code as HTML 4.01.
</td>
</tr>
<tr>
<td><strong><code>ENT_XML1</code></strong></td>
<td>
Handle code as XML 1.
</td>
</tr>
<tr>
<td><strong><code>ENT_XHTML</code></strong></td>
<td>
Handle code as XHTML.
</td>
</tr>
<tr>
<td><strong><code>ENT_HTML5</code></strong></td>
<td>
Handle code as HTML 5.
</td>
</tr>
</tbody>
</table>
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">encoding</code></em></span>
<dd>
<p class="para">
Defines encoding used in conversion.
If omitted, the default value for this argument is ISO-8859-1 in
versions of PHP prior to 5.4.0, and UTF-8 from PHP 5.4.0 onwards.
</p>
<p class="para">
For the purposes of this function, the encodings
<em>ISO-8859-1</em>, <em>ISO-8859-15</em>,
<em>UTF-8</em>, <em>cp866</em>,
<em>cp1251</em>, <em>cp1252</em>, and
<em>KOI8-R</em> are effectively equivalent, provided the
<em><code class="parameter">string</code></em> itself is valid for the encoding, as
the characters affected by <span class="function"><strong>htmlspecialchars()</strong></span> occupy
the same positions in all of these encodings.
</p>
<p class="para">
The following character sets are supported:
<table class="doctable table">
<caption><strong>Supported charsets</strong></caption>
<thead>
<tr>
<th>Charset</th>
<th>Aliases</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>ISO-8859-1</td>
<td>ISO8859-1</td>
<td>
Western European, Latin-1.
</td>
</tr>
<tr>
<td>ISO-8859-5</td>
<td>ISO8859-5</td>
<td>
Little used cyrillic charset (Latin/Cyrillic).
</td>
</tr>
<tr>
<td>ISO-8859-15</td>
<td>ISO8859-15</td>
<td>
Western European, Latin-9. Adds the Euro sign, French and Finnish
letters missing in Latin-1 (ISO-8859-1).
</td>
</tr>
<tr>
<td>UTF-8</td>
<td class="empty"> </td>
<td>
ASCII compatible multi-byte 8-bit Unicode.
</td>
</tr>
<tr>
<td>cp866</td>
<td>ibm866, 866</td>
<td>
DOS-specific Cyrillic charset.
</td>
</tr>
<tr>
<td>cp1251</td>
<td>Windows-1251, win-1251, 1251</td>
<td>
Windows-specific Cyrillic charset.
</td>
</tr>
<tr>
<td>cp1252</td>
<td>Windows-1252, 1252</td>
<td>
Windows specific charset for Western European.
</td>
</tr>
<tr>
<td>KOI8-R</td>
<td>koi8-ru, koi8r</td>
<td>
Russian.
</td>
</tr>
<tr>
<td>BIG5</td>
<td>950</td>
<td>
Traditional Chinese, mainly used in Taiwan.
</td>
</tr>
<tr>
<td>GB2312</td>
<td>936</td>
<td>
Simplified Chinese, national standard character set.
</td>
</tr>
<tr>
<td>BIG5-HKSCS</td>
<td class="empty"> </td>
<td>
Big5 with Hong Kong extensions, Traditional Chinese.
</td>
</tr>
<tr>
<td>Shift_JIS</td>
<td>SJIS, SJIS-win, cp932, 932</td>
<td>
Japanese
</td>
</tr>
<tr>
<td>EUC-JP</td>
<td>EUCJP, eucJP-win</td>
<td>
Japanese
</td>
</tr>
<tr>
<td>MacRoman</td>
<td class="empty"> </td>
<td>
Charset that was used by Mac OS.
</td>
</tr>
<tr>
<td><em>''</em></td>
<td class="empty"> </td>
<td>
An empty string activates detection from script encoding (Zend multibyte),
<a href="ini.core.html#ini.default-charset" class="link">default_charset</a> and current
locale (see <span class="function"><a href="function.nl-langinfo.html" class="function">nl_langinfo()</a></span> and
<span class="function"><a href="function.setlocale.html" class="function">setlocale()</a></span>), in this order. Not recommended.
</td>
</tr>
</tbody>
</table>
<blockquote class="note"><p><strong class="note">Note</strong>:
<span class="simpara">
Any other character sets are not recognized. The default encoding will be
used instead and a warning will be emitted.
</span>
</p></blockquote>
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">double_encode</code></em></span>
<dd>
<p class="para">
When <em><code class="parameter">double_encode</code></em> is turned off PHP will not
encode existing html entities, the default is to convert everything.
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.htmlspecialchars-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
The converted <span class="type"><a href="language.types.string.html" class="type string">string</a></span>.
</p>
<p class="para">
If the input <em><code class="parameter">string</code></em> contains an invalid code unit
sequence within the given <em><code class="parameter">encoding</code></em> an empty string
will be returned, unless either the <strong><code>ENT_IGNORE</code></strong> or
<strong><code>ENT_SUBSTITUTE</code></strong> flags are set.
</p>
</div>
<div class="refsect1 changelog" id="refsect1-function.htmlspecialchars-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>5.4.0</td>
<td>
The default value for the <em><code class="parameter">encoding</code></em> parameter was
changed to UTF-8.
</td>
</tr>
<tr>
<td>5.4.0</td>
<td>
The constants <strong><code>ENT_SUBSTITUTE</code></strong>, <strong><code>ENT_DISALLOWED</code></strong>,
<strong><code>ENT_HTML401</code></strong>, <strong><code>ENT_XML1</code></strong>,
<strong><code>ENT_XHTML</code></strong> and <strong><code>ENT_HTML5</code></strong> were added.
</td>
</tr>
<tr>
<td>5.3.0</td>
<td>
The constant <strong><code>ENT_IGNORE</code></strong> was added.
</td>
</tr>
<tr>
<td>5.2.3</td>
<td>
The <em><code class="parameter">double_encode</code></em> parameter was added.
</td>
</tr>
<tr>
<td>4.1.0</td>
<td>
The <em><code class="parameter">encoding</code></em> parameter was added.
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.htmlspecialchars-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-4839">
<p><strong>Example #1 <span class="function"><strong>htmlspecialchars()</strong></span> example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$new </span><span style="color: #007700">= </span><span style="color: #0000BB">htmlspecialchars</span><span style="color: #007700">(</span><span style="color: #DD0000">"<a href='test'>Test</a>"</span><span style="color: #007700">, </span><span style="color: #0000BB">ENT_QUOTES</span><span style="color: #007700">);<br />echo </span><span style="color: #0000BB">$new</span><span style="color: #007700">; </span><span style="color: #FF8000">// &lt;a href=&#039;test&#039;&gt;Test&lt;/a&gt;<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</div>
<div class="refsect1 notes" id="refsect1-function.htmlspecialchars-notes">
<h3 class="title">Notes</h3>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
Note that this function does not translate anything beyond what
is listed above. For full entity translation, see
<span class="function"><a href="function.htmlentities.html" class="function">htmlentities()</a></span>.
</p>
</p></blockquote>
</div>
<div class="refsect1 seealso" id="refsect1-function.htmlspecialchars-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="function"><a href="function.get-html-translation-table.html" class="function" rel="rdfs-seeAlso">get_html_translation_table()</a> - Returns the translation table used by htmlspecialchars and htmlentities</span></li>
<li class="member"> <span class="function"><a href="function.htmlspecialchars-decode.html" class="function" rel="rdfs-seeAlso">htmlspecialchars_decode()</a> - Convert special HTML entities back to characters</span></li>
<li class="member"> <span class="function"><a href="function.strip-tags.html" class="function" rel="rdfs-seeAlso">strip_tags()</a> - Strip HTML and PHP tags from a string</span></li>
<li class="member"> <span class="function"><a href="function.htmlentities.html" class="function" rel="rdfs-seeAlso">htmlentities()</a> - Convert all applicable characters to HTML entities</span></li>
<li class="member"> <span class="function"><a href="function.nl2br.html" class="function" rel="rdfs-seeAlso">nl2br()</a> - Inserts HTML line breaks before all newlines in a string</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="function.htmlspecialchars-decode.html">htmlspecialchars_decode</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.implode.html">implode</a></div>
<div class="up"><a href="ref.strings.html">String Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
