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

<!-- $Revision$ -->

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

<refnamediv>

<refname>utf8_decode</refname>

<refpurpose>

Converts a string from UTF-8 to ISO-8859-1, replacing invalid or unrepresentable

characters

</refpurpose>

</refnamediv>

<refsynopsisdiv>

&warn.deprecated.function-8-2-0;

</refsynopsisdiv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<modifier role="attribute">#[\Deprecated]</modifier>

<type>string</type><methodname>utf8_decode</methodname>

<methodparam><type>string</type><parameter>string</parameter></methodparam>

</methodsynopsis>

<para>

This function converts the string <parameter>string</parameter> from the

<literal>UTF-8</literal> encoding to <literal>ISO-8859-1</literal>. Bytes

in the string which are not valid <literal>UTF-8</literal>, and

<literal>UTF-8</literal> characters which do not exist in

<literal>ISO-8859-1</literal> (that is, code points above

<literal>U+00FF</literal>) are replaced with <literal>?</literal>.

</para>

<note>

<para>

Many web pages marked as using the <literal>ISO-8859-1</literal> character

encoding actually use the similar <literal>Windows-1252</literal> encoding,

and web browsers will interpret <literal>ISO-8859-1</literal> web pages as

<literal>Windows-1252</literal>. <literal>Windows-1252</literal> features

additional printable characters, such as the Euro sign

(<literal>€</literal>) and curly quotes (<literal>“</literal>

<literal>”</literal>), instead of certain <literal>ISO-8859-1</literal>

control characters. This function will not convert such

<literal>Windows-1252</literal> characters correctly. Use a different

function if <literal>Windows-1252</literal> conversion is required.

</para>

</note>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

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

<listitem>

<para>

A UTF-8 encoded string.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Returns the ISO-8859-1 translation of <parameter>string</parameter>.

</para>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<para>

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>8.2.0</entry>

<entry>

This function has been deprecated.

</entry>

</row>

<row>

<entry>7.2.0</entry>

<entry>

This function has been moved from the XML extension to the core of PHP.

In previous versions, it was only available if the XML extension was installed.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<example>

<title>Basic examples</title>

<programlisting role="php">

<![CDATA[

<?php

// Convert the string 'Zoë' from UTF-8 to ISO 8859-1

$utf8_string = "\x5A\x6F\xC3\xAB";

$iso8859_1_string = utf8_decode($utf8_string);

echo bin2hex($iso8859_1_string), "\n";

// Invalid UTF-8 sequences are replaced with '?'

$invalid_utf8_string = "\xC3";

$iso8859_1_string = utf8_decode($invalid_utf8_string);

var_dump($iso8859_1_string);

// Characters which don't exist in ISO 8859-1, such as

// '€' (Euro Sign) are also replaced with '?'

$utf8_string = "\xE2\x82\xAC";

$iso8859_1_string = utf8_decode($utf8_string);

var_dump($iso8859_1_string);

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

5a6feb

string(1) "?"

string(1) "?"

]]>

</screen>

</example>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<note>

<title>Deprecation and alternatives</title>

<para>

This function is <emphasis>deprecated</emphasis> as of PHP 8.2.0,

and will be removed in a future version. Existing uses should be checked

and replaced with appropriate alternatives.

</para>

<para>

Similar functionality can be achieved with <function>mb_convert_encoding</function>,

which supports ISO-8859-1 and many other character encodings.

<informalexample>

<programlisting role="php">

<![CDATA[

<?php

$utf8_string = "\xC3\xAB"; // 'ë' (e with diaeresis) in UTF-8

$iso8859_1_string = mb_convert_encoding($utf8_string, 'ISO-8859-1', 'UTF-8');

echo bin2hex($iso8859_1_string), "\n";

$utf8_string = "\xCE\xBB"; // 'λ' (Greek lower-case lambda) in UTF-8

$iso8859_7_string = mb_convert_encoding($utf8_string, 'ISO-8859-7', 'UTF-8');

echo bin2hex($iso8859_7_string), "\n";

$utf8_string = "\xE2\x82\xAC"; // '€' (Euro sign) in UTF-8 (not present in ISO-8859-1)

$windows_1252_string = mb_convert_encoding($utf8_string, 'Windows-1252', 'UTF-8');

echo bin2hex($windows_1252_string), "\n";

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

eb

eb

80

]]>

</screen>

</informalexample>

</para>

<para>

Other options which may be available depending on the extensions installed are

<methodname>UConverter::transcode</methodname> and <function>iconv</function>.

</para>

<para>

The following all give the same result:

<informalexample>

<programlisting role="php">

<![CDATA[

<?php

$utf8_string = "\x5A\x6F\xC3\xAB"; // 'Zoë' in UTF-8

$iso8859_1_string = utf8_decode($utf8_string);

echo bin2hex($iso8859_1_string), "\n";

$iso8859_1_string = mb_convert_encoding($utf8_string, 'ISO-8859-1', 'UTF-8');

echo bin2hex($iso8859_1_string), "\n";

$iso8859_1_string = iconv('UTF-8', 'ISO-8859-1', $utf8_string);

echo bin2hex($iso8859_1_string), "\n";

$iso8859_1_string = UConverter::transcode($utf8_string, 'ISO-8859-1', 'UTF8');

echo bin2hex($iso8859_1_string), "\n";

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

5a6feb

5a6feb

5a6feb

5a6feb

]]>

</screen>

</informalexample>

Specifying <literal>'?'</literal> as the <literal>'to_subst'</literal> option

to <methodname>UConverter::transcode</methodname> gives the same result as

<function>utf8_decode</function> for strings which are invalid or which can not

be represented in ISO 8859-1.

<informalexample>

<programlisting role="php">

<![CDATA[

<?php

$utf8_string = "\xE2\x82\xAC"; // € (Euro Sign) does not exist in ISO 8859-1

$iso8859_1_string = UConverter::transcode(

$utf8_string, 'ISO-8859-1', 'UTF-8', ['to_subst' => '?']

);

var_dump($iso8859_1_string);

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

sring(1) "?"

]]>

</screen>

</informalexample>

</para>

</note>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>utf8_encode</function></member>

<member><function>mb_convert_encoding</function></member>

<member><methodname>UConverter::transcode</methodname></member>

<member><function>iconv</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

-->