<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.html-entity-decode">
 <refnamediv>
  <refname>html_entity_decode</refname>
  <refpurpose>Convert HTML entities to their corresponding characters</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>html_entity_decode</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>
  </methodsynopsis>
  <para>
   <function>html_entity_decode</function> is the opposite of
   <function>htmlentities</function> in that it converts HTML entities
   in the <parameter>string</parameter> to their corresponding characters.
  </para>
  <para>
   More precisely, this function decodes all the entities (including all numeric
   entities) that a) are necessarily valid for the chosen document type — i.e.,
   for XML, this function does not decode named entities that might be defined
   in some DTD — and b) whose character or characters are in the coded character
   set associated with the chosen encoding and are permitted in the chosen
   document type. All other entities are left as is.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>string</parameter></term>
     <listitem>
      <para>
       The input string.
      </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 and
       which document type to use. 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_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;
      &reference.strings.charsets;
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the decoded string.
  </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>
        Default encoding changed from ISO-8859-1 to UTF-8.
       </entry>
      </row>
      <row>
       <entry>5.4.0</entry>
       <entry>
        The constants <constant>ENT_HTML401</constant>, <constant>ENT_XML1</constant>,
        <constant>ENT_XHTML</constant> and <constant>ENT_HTML5</constant> were added.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Decoding HTML entities</title>
    <programlisting role="php">
<![CDATA[
<?php
$orig = "I'll \"walk\" the <b>dog</b> now";

$a = htmlentities($orig);

$b = html_entity_decode($a);

echo $a; // I'll &quot;walk&quot; the &lt;b&gt;dog&lt;/b&gt; now

echo $b; // I'll "walk" the <b>dog</b> now
?>
]]>
    </programlisting>
   </example>   
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    You might wonder why trim(html_entity_decode('&amp;nbsp;')); doesn't
    reduce the string to an empty string, that's because the '&amp;nbsp;'
    entity is not ASCII code 32 (which is stripped by
    <function>trim</function>) but ASCII code 160 (0xa0) in the default ISO
    8859-1 encoding.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>htmlentities</function></member>
    <member><function>htmlspecialchars</function></member>
    <member><function>get_html_translation_table</function></member>
    <member><function>urldecode</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
-->