utf8_decode()

Функция utf8_decode() — это встроенная функция PHP, которая преобразует строку из кодировки UTF-8 в ISO-8859-1 (также называемую Latin-1). UTF-8 может представлять любой символ Unicode, тогда как ISO-8859-1 — однобайтовая кодировка, охватывающая только первые 256 кодовых точек Unicode (буквы западноевропейских языков, цифры и знаки пунктуации).

На этой странице описано, что делает utf8_decode(), когда именно она нужна, чем её заменить и как она ведёт себя с символами, выходящими за пределы ISO-8859-1.

Когда (и нужно ли) использовать её

utf8_decode() нужна только тогда, когда вы передаёте текст в кодировке UTF-8 в устаревшую систему, которая понимает только ISO-8859-1 — например, в старый столбец базы данных, отчёт с фиксированной шириной или сторонний API, созданный до появления Unicode. Для всего нового храните данные в UTF-8 от начала до конца — и эта функция вам никогда не понадобится.

Важное ограничение: в ISO-8859-1 нет места для таких символов, как €, ™, эмодзи или любой нелатинский алфавит. Когда utf8_decode() встречает символ, который невозможно представить, она заменяет его знаком вопроса (?) — исходный символ теряется. Именно поэтому функция является деструктивной и почти всегда лучше оставаться в кодировке UTF-8.

Синтаксис

Синтаксис функции utf8_decode() выглядит следующим образом:

utf8_decode(string $string): string

Возвращаемое значение: преобразованная строка в кодировке ISO-8859-1. Байты, не являющиеся корректным UTF-8, и символы, не имеющие эквивалента в ISO-8859-1, заменяются знаком вопроса (?).

Примеры использования

Рассмотрим несколько практических примеров использования utf8_decode() в PHP.

Пример 1: преобразование текста из UTF-8 в ISO-8859-1

Строка "Zoë" хранится в скрипте в кодировке UTF-8, где ë занимает два байта (c3 ab). После декодирования ë становится одним байтом ISO-8859-1 eb. Мы выводим необработанные байты с помощью bin2hex(), чтобы изменение на уровне байтов было наглядным:

Преобразование текста из UTF-8 в ISO-8859-1 в PHP

Результат:

5a6feb

Четыре UTF-8 байта (Z, o и двухбайтовый ë) сжимаются до трёх байтов ISO-8859-1: 5a (Z), 6f (o) и eb (ë). Строка стала на один байт короче, потому что символ с диакритическим знаком теперь кодируется одним байтом вместо двух.

Пример 2: символы, которые невозможно представить

Поскольку ISO-8859-1 имеет только 256 кодовых точек, любой символ за пределами этого диапазона теряется. Знак евро (€) — классический пример: его нет в Latin-1:

<?php

echo utf8_decode("Price: €5");  // Price: ?5

?>

€ заменяется на ?. Если вам нужно сохранить подобные символы, не преобразуйте текст в ISO-8859-1 — оставьте его в UTF-8 или используйте более богатую целевую кодировку.

Пример 3: чтение текста в UTF-8 из XML

SimpleXML всегда разбирает XML как UTF-8. Если вам нужно передать этот текст в систему с Latin-1, декодируйте каждое значение по мере чтения с помощью simplexml_load_file():

Преобразование текста из UTF-8, полученного из XML, в PHP

<?php

$xml = simplexml_load_file("data.xml");
foreach ($xml->item as $item) {
    $title = utf8_decode((string) $item->title);
    $description = utf8_decode((string) $item->description);
    echo "$title: $description\n";
}

?>

Этот код загружает data.xml, перебирает все элементы <item> и декодирует текст <title> и <description> из UTF-8 в ISO-8859-1. Приведение каждого узла к типу (string) сначала превращает SimpleXMLElement в обычную строку перед декодированием.

Чтобы этот пример работал, data.xml должен содержать структуру следующего вида:

<root>
  <item>
    <title>Example Title</title>
    <description>Example Description</description>
  </item>
</root>

Заключение

utf8_decode() преобразует текст в кодировке UTF-8 в ISO-8859-1, отбрасывая любой символ, который Latin-1 не может представить. Функция удобна для работы с устаревшими системами, однако начиная с PHP 8.2+ она объявлена устаревшей и является деструктивной, поэтому предпочтительнее использовать mb_convert_encoding() или iconv() и по возможности хранить данные в UTF-8.

Для выполнения обратного преобразования смотрите utf8_encode(). Подробнее о работе с текстом в PHP — в справочнике строковых функций PHP.

Практика