reference/strings/functions/utf8-decode.xml
b676d0b9c968ebb0b7429835f2f6bd364275eed1
b676d0b9c968ebb0b7429835f2f6bd364275eed1
...
...
@@ -9,6 +9,10 @@
9
9
</refpurpose>
10
10
</refnamediv>
11
11
12
+
<refsynopsisdiv>
13
+
&warn.deprecated.function-8-2-0;
14
+
</refsynopsisdiv>
15
+
12
16
<refsect1 role="description">
13
17
&reftitle.description;
14
18
<methodsynopsis>
...
...
@@ -76,6 +80,12 @@
76
80
</thead>
77
81
<tbody>
78
82
<row>
83
+
<entry>8.2.0</entry>
84
+
<entry>
85
+
This function has been deprecated.
86
+
</entry>
87
+
</row>
88
+
<row>
79
89
<entry>7.2.0</entry>
80
90
<entry>
81
91
This function has been moved from the XML extension to the core of PHP.
...
...
@@ -124,6 +134,108 @@ string(1) "?"
124
134
</example>
125
135
</refsect1>
126
136
137
+
<refsect1 role="notes">
138
+
&reftitle.notes;
139
+
<note>
140
+
<title>Deprecation and alternatives</title>
141
+
<para>
142
+
This function is <emphasis>deprecated</emphasis> as of PHP 8.2.0,
143
+
and will be removed in a future version. Existing uses should be checked
144
+
and replaced with appropriate alternatives.
145
+
</para>
146
+
<para>
147
+
Similar functionality can be achieved with <function>mb_convert_encoding</function>,
148
+
which supports ISO-8859-1 and many other character encodings.
149
+
<informalexample>
150
+
<programlisting role="php">
151
+
<![CDATA[
152
+
<?php
153
+
$utf8_string = "\xC3\xAB"; // 'ë' (e with diaeresis) in UTF-8
154
+
$iso8859_1_string = mb_convert_encoding($utf8_string, 'ISO-8859-1', 'UTF-8');
155
+
echo bin2hex($iso8859_1_string), "\n";
156
+
157
+
$utf8_string = "\xCE\xBB"; // 'λ' (Greek lower-case lambda) in UTF-8
158
+
$iso8859_7_string = mb_convert_encoding($utf8_string, 'ISO-8859-7', 'UTF-8');
159
+
echo bin2hex($iso8859_7_string), "\n";
160
+
161
+
$utf8_string = "\xE2\x82\xAC"; // '€' (Euro sign) in UTF-8 (not present in ISO-8859-1)
162
+
$windows_1252_string = mb_convert_encoding($utf8_string, 'Windows-1252', 'UTF-8');
163
+
echo bin2hex($windows_1252_string), "\n";
164
+
?>
165
+
]]>
166
+
</programlisting>
167
+
&example.outputs;
168
+
<screen>
169
+
<![CDATA[
170
+
eb
171
+
eb
172
+
80
173
+
]]>
174
+
</screen>
175
+
</informalexample>
176
+
</para>
177
+
<para>
178
+
Other options which may be available depending on the extensions installed are
179
+
<methodname>UConverter::transcode</methodname> and <function>iconv</function>.
180
+
</para>
181
+
<para>
182
+
The following all give the same result:
183
+
<informalexample>
184
+
<programlisting role="php">
185
+
<![CDATA[
186
+
<?php
187
+
$utf8_string = "\x5A\x6F\xC3\xAB"; // 'Zoë' in UTF-8
188
+
$iso8859_1_string = utf8_decode($utf8_string);
189
+
echo bin2hex($iso8859_1_string), "\n";
190
+
191
+
$iso8859_1_string = mb_convert_encoding($utf8_string, 'ISO-8859-1', 'UTF-8');
192
+
echo bin2hex($iso8859_1_string), "\n";
193
+
194
+
$iso8859_1_string = iconv('UTF-8', 'ISO-8859-1', $utf8_string);
195
+
echo bin2hex($iso8859_1_string), "\n";
196
+
197
+
$iso8859_1_string = UConverter::transcode($utf8_string, 'ISO-8859-1', 'UTF8');
198
+
echo bin2hex($iso8859_1_string), "\n";
199
+
?>
200
+
]]>
201
+
</programlisting>
202
+
&example.outputs;
203
+
<screen>
204
+
<![CDATA[
205
+
5a6feb
206
+
5a6feb
207
+
5a6feb
208
+
5a6feb
209
+
]]>
210
+
</screen>
211
+
</informalexample>
212
+
Specifying <literal>'?'</literal> as the <literal>'to_subst'</literal> option
213
+
to <methodname>UConverter::transcode</methodname> gives the same result as
214
+
<function>utf8_decode</function> for strings which are invalid or which can not
215
+
be represented in ISO 8859-1.
216
+
<informalexample>
217
+
<programlisting role="php">
218
+
<![CDATA[
219
+
<?php
220
+
$utf8_string = "\xE2\x82\xAC"; // € (Euro Sign) does not exist in ISO 8859-1
221
+
$iso8859_1_string = UConverter::transcode(
222
+
$utf8_string, 'ISO-8859-1', 'UTF-8', ['to_subst' => '?']
223
+
);
224
+
var_dump($iso8859_1_string);
225
+
?>
226
+
]]>
227
+
</programlisting>
228
+
&example.outputs;
229
+
<screen>
230
+
<![CDATA[
231
+
sring(1) "?"
232
+
]]>
233
+
</screen>
234
+
</informalexample>
235
+
</para>
236
+
</note>
237
+
</refsect1>
238
+
127
239
<refsect1 role="seealso">
128
240
&reftitle.seealso;
129
241
<para>
130
242