html-entity-decode.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.html-entity-decode" xmlns="http://docbook.org/ns/docbook">
 <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_QUOTES | ENT_SUBSTITUTE | ENT_HTML401</initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>encoding</parameter><initializer>&null;</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_QUOTES | ENT_SUBSTITUTE | 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_SUBSTITUTE</constant></entry>
           <entry>
            Replace invalid code unit sequences with a Unicode Replacement Character
            U+FFFD (UTF-8) or &amp;#xFFFD; (otherwise) instead of returning an empty string.
           </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;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.1.0</entry>
      <entry>
       <parameter>flags</parameter> changed from <constant>ENT_COMPAT</constant> to <constant>ENT_QUOTES</constant> | <constant>ENT_SUBSTITUTE</constant> | <constant>ENT_HTML401</constant>.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       <parameter>encoding</parameter> is nullable now.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </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
-->