<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.htmlspecialchars" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>htmlspecialchars</refname>
<refpurpose>Convert special characters to HTML entities</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>htmlspecialchars</methodname>
<methodparam><type>string</type><parameter>string</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>ENT_COMPAT | ENT_HTML401</initializer></methodparam>
<methodparam choice="opt"><type>string</type><parameter>encoding</parameter><initializer>ini_get("default_charset")</initializer></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>double_encode</parameter><initializer>true</initializer></methodparam>
</methodsynopsis>
<para>
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 <function>htmlentities</function>
instead.
</para>
<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 <function>htmlentities</function> (which only encodes
substrings that have named entity equivalents) may be insufficient.
You may have to use <function>mb_encode_numericentity</function> instead.
</para>
<para>
<table>
<title>Performed translations</title>
<tgroup cols="2">
<thead>
<row>
<entry>Character</entry>
<entry>Replacement</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>&</literal> (ampersand)</entry>
<entry><literal>&amp;</literal></entry>
</row>
<row>
<entry><literal>"</literal> (double quote)</entry>
<entry><literal>&quot;</literal>, unless <constant>ENT_NOQUOTES</constant> is set</entry>
</row>
<row>
<entry><literal>'</literal> (single quote)</entry>
<entry>
<literal>&#039;</literal> (for <constant>ENT_HTML401</constant>) or <literal>&apos;</literal> (for
<constant>ENT_XML1</constant>, <constant>ENT_XHTML</constant> or
<constant>ENT_HTML5</constant>), but only when
<constant>ENT_QUOTES</constant> is set
</entry>
</row>
<row>
<entry><literal><</literal> (less than)</entry>
<entry><literal>&lt;</literal></entry>
</row>
<row>
<entry><literal>></literal> (greater than)</entry>
<entry><literal>&gt;</literal></entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>string</parameter></term>
<listitem>
<para>
The <type>string</type> being converted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<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
<literal>ENT_COMPAT | ENT_HTML401</literal>.
<table>
<title>Available <parameter>flags</parameter> constants</title>
<tgroup cols="2">
<thead>
<row>
<entry>Constant Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><constant>ENT_COMPAT</constant></entry>
<entry>Will convert double-quotes and leave single-quotes alone.</entry>
</row>
<row>
<entry><constant>ENT_QUOTES</constant></entry>
<entry>Will convert both double and single quotes.</entry>
</row>
<row>
<entry><constant>ENT_NOQUOTES</constant></entry>
<entry>Will leave both double and single quotes unconverted.</entry>
</row>
<row>
<entry><constant>ENT_IGNORE</constant></entry>
<entry>
Silently discard invalid code unit sequences instead of returning
an empty string. Using this flag is discouraged as it
<link xlink:href="&url.delete.nonchars;">may have security implications</link>.
</entry>
</row>
<row>
<entry><constant>ENT_SUBSTITUTE</constant></entry>
<entry>
Replace invalid code unit sequences with a Unicode Replacement Character
U+FFFD (UTF-8) or &#xFFFD; (otherwise) instead of returning an empty string.
</entry>
</row>
<row>
<entry><constant>ENT_DISALLOWED</constant></entry>
<entry>
Replace invalid code points for the given document type with a
Unicode Replacement Character U+FFFD (UTF-8) or &#xFFFD;
(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.
</entry>
</row>
<row>
<entry><constant>ENT_HTML401</constant></entry>
<entry>
Handle code as HTML 4.01.
</entry>
</row>
<row>
<entry><constant>ENT_XML1</constant></entry>
<entry>
Handle code as XML 1.
</entry>
</row>
<row>
<entry><constant>ENT_XHTML</constant></entry>
<entry>
Handle code as XHTML.
</entry>
</row>
<row>
<entry><constant>ENT_HTML5</constant></entry>
<entry>
Handle code as HTML 5.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>encoding</parameter></term>
<listitem>
&strings.parameter.encoding;
<para>
For the purposes of this function, the encodings
<literal>ISO-8859-1</literal>, <literal>ISO-8859-15</literal>,
<literal>UTF-8</literal>, <literal>cp866</literal>,
<literal>cp1251</literal>, <literal>cp1252</literal>, and
<literal>KOI8-R</literal> are effectively equivalent, provided the
<parameter>string</parameter> itself is valid for the encoding, as
the characters affected by <function>htmlspecialchars</function> occupy
the same positions in all of these encodings.
</para>
&reference.strings.charsets;
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>double_encode</parameter></term>
<listitem>
<para>
When <parameter>double_encode</parameter> is turned off PHP will not
encode existing html entities, the default is to convert everything.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The converted <type>string</type>.
</para>
<para>
If the input <parameter>string</parameter> contains an invalid code unit
sequence within the given <parameter>encoding</parameter> an empty string
will be returned, unless either the <constant>ENT_IGNORE</constant> or
<constant>ENT_SUBSTITUTE</constant> flags are set.
</para>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
&strings.changelog.encoding;
<row>
<entry>5.4.0</entry>
<entry>
The default value for the <parameter>encoding</parameter> parameter was
changed to UTF-8.
</entry>
</row>
<row>
<entry>5.4.0</entry>
<entry>
The constants <constant>ENT_SUBSTITUTE</constant>, <constant>ENT_DISALLOWED</constant>,
<constant>ENT_HTML401</constant>, <constant>ENT_XML1</constant>,
<constant>ENT_XHTML</constant> and <constant>ENT_HTML5</constant> were added.
</entry>
</row>
<row>
<entry>5.3.0</entry>
<entry>
The constant <constant>ENT_IGNORE</constant> was added.
</entry>
</row>
<row>
<entry>5.2.3</entry>
<entry>
The <parameter>double_encode</parameter> parameter was added.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>htmlspecialchars</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$new = htmlspecialchars("<a href='test'>Test</a>", ENT_QUOTES);
echo $new; // <a href='test'>Test</a>
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<para>
Note that this function does not translate anything beyond what
is listed above. For full entity translation, see
<function>htmlentities</function>.
</para>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>get_html_translation_table</function></member>
<member><function>htmlspecialchars_decode</function></member>
<member><function>strip_tags</function></member>
<member><function>htmlentities</function></member>
<member><function>nl2br</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:"~/.phpdoc/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
-->