<?xml version="1.0" encoding="utf-8"?>

<refentry xml:id="function.html-entity-decode" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>html_entity_decode</refname>

<refpurpose>HTML エンティティを対応する文字に変換する</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> は

<function>htmlentities</function> の反対で、<parameter>string</parameter>

にある HTML エンティティを対応する文字に変換します。

</para>

<para>

厳密に言うと、この関数は次の二つの条件を満たすすべての (数値エンティティを含む)

エンティティをデコードします。それ以外のエンティティは、何も変換しません。

1) 選択したドキュメントタイプで必然的に有効になるもの。つまり

XML の場合には、DTD で定義されている名前付きエンティティはデコードしません。

2) 選択したエンコーディングに関連づけられている符号化文字集合に含まれる文字で、

選択したドキュメントタイプで許可されているもの。

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>string</parameter></term>

<listitem>

<para>

入力文字列。

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>flags</parameter></term>

<listitem>

<para>

以下のフラグのビットマスクによる組み合わせで、クォートの扱いやドキュメントの形式を指定します。

デフォルトは <literal>ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401</literal> です。

<table>

<title>使用可能な <parameter>flags</parameter> 定数</title>

<tgroup cols="2">

<thead>

<row>

<entry>定数名</entry>

<entry>説明</entry>

</row>

</thead>

<tbody>

<row>

<entry><constant>ENT_COMPAT</constant></entry>

<entry>ダブルクォートを変換し、シングルクォートはそのままにします。</entry>

</row>

<row>

<entry><constant>ENT_QUOTES</constant></entry>

<entry>ダブルクォート、シングルクォートの両方を変換します。</entry>

</row>

<row>

<entry><constant>ENT_NOQUOTES</constant></entry>

<entry>ダブルクォート、シングルクォートの両方とも変換しません。</entry>

</row>

<row>

<entry><constant>ENT_SUBSTITUTE</constant></entry>

<entry>

無効な符号単位シーケンスを含む文字列を渡したときに、

空の文字列を返すのではなく Unicode の置換文字に置き換えます。

UTF-8 の場合は U+FFFD、それ以外の場合は &amp;#FFFD; となります。

</entry>

</row>

<row>

<entry><constant>ENT_HTML401</constant></entry>

<entry>

コードを HTML 4.01 として処理します。

</entry>

</row>

<row>

<entry><constant>ENT_XML1</constant></entry>

<entry>

コードを XML 1 として処理します。

</entry>

</row>

<row>

<entry><constant>ENT_XHTML</constant></entry>

<entry>

コードを XHTML として処理します。

</entry>

</row>

<row>

<entry><constant>ENT_HTML5</constant></entry>

<entry>

コードを 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>

デコードされた文字列を返します。

</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> のデフォルト値が

<constant>ENT_COMPAT</constant> から

<constant>ENT_QUOTES</constant> | <constant>ENT_SUBSTITUTE</constant> | <constant>ENT_HTML401</constant>

に変更されました。

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

<parameter>encoding</parameter> は、nullable になりました。

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>HTML エンティティのデコード</title>

<programlisting role="php">

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<note>

<para>

trim(html_entity_decode('&amp;nbsp;')); の結果が空の文字列に

ならないことを疑問に思う人もいるでしょう。なぜそうなるのかというと、

デフォルトのエンコーディング ISO-8859-1 では

'&amp;nbsp;' エンティティが ASCII コード 32 (これは

<function>trim</function> で取り除かれる) ではなく

ASCII コード 160 (0xa0) に変換されるからです。

</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>