utf8_encode()

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

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

Устарела, затем удалена. utf8_encode() была признана устаревшей в PHP 8.2 и удалена в PHP 8.3. В новом коде следует использовать mb_convert_encoding() или iconv() — см. раздел Современные альтернативы ниже. Эта страница документирует устаревшую функцию для многочисленных кодовых баз, которые по-прежнему на неё опираются.

Что здесь означает «кодировка»

Кодировка символов — это соответствие между символами и представляющими их байтами. ISO-8859-1 — однобайтовая кодировка: каждый символ занимает ровно один байт (256 возможных значений) и охватывает буквы западноевропейских языков, такие как é, ñ и ü. UTF-8 — кодировка переменной ширины, где те же символы с диакритическими знаками занимают два байта.

utf8_encode() выполняет одну конкретную задачу: читает каждый байт входных данных как кодовую позицию ISO-8859-1 и записывает его в виде эквивалентной последовательности байтов UTF-8. Она не определяет кодировку входных данных — всегда предполагает, что входные данные в ISO-8859-1. Если передать ей строку, уже закодированную в UTF-8, на выходе получится искажённый «мохибаке» (двойное кодирование).

Синтаксис

utf8_encode(string $string): string

Возвращаемое значение: тот же текст, перекодированный в UTF-8.

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

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

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

Предположим, у вас есть строка в кодировке ISO-8859-1, которую нужно преобразовать в UTF-8. Для этого можно использовать utf8_encode():

Этот код определяет строковую переменную $text, содержащую текст в ISO-8859-1, преобразует его в UTF-8 с помощью utf8_encode() и выводит результат. Обратите внимание на оговорку в комментарии: исходная строка должна действительно быть в ISO-8859-1. Если ваш редактор сохраняет файл как UTF-8, символ é уже занимает два байта, и utf8_encode() превратит его в é.

Пример 2: Наблюдение за изменением на уровне байтов

Чтобы наглядно увидеть преобразование, проверьте длину в байтах до и после. Символ с диакритическим знаком расширяется с одного байта до двух:

<?php
$latin1 = "\xE9";            // a single byte: 'é' in ISO-8859-1
echo strlen($latin1);        // 1
$utf8 = utf8_encode($latin1);
echo strlen($utf8);          // 2  -> the bytes 0xC3 0xA9
echo bin2hex($utf8);         // c3a9
?>

strlen() считает байты, а не символы, поэтому одна и та же буква имеет длину 1 в Latin-1 и 2 в UTF-8. Именно это расширение с одного байта до двух обеспечивает корректное отображение преобразованного текста в контексте UTF-8.

Пример 3: Преобразование текста XML в кодировке ISO-8859-1

Предположим, у вас есть XML-файл, объявленный как ISO-8859-1, который нужно прочитать и преобразовать в UTF-8. Вы можете использовать библиотеку SimpleXML для чтения файла и utf8_encode() для преобразования каждого значения:

<?php
$xml = simplexml_load_file("data.xml");
foreach ($xml->item as $item) {
  $title = utf8_encode($item->title);
  $description = utf8_encode($item->description);
  echo "$title: $description\n";
}
?>

Этот код загружает XML-файл, объявленный как ISO-8859-1, с помощью simplexml_load_file(), перебирает каждый элемент <item> и преобразует текст <title> и <description> в UTF-8 перед выводом. (Значения SimpleXMLElement приводятся к строкам функцией utf8_encode().)

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

Используйте utf8_encode() только при одновременном выполнении всех следующих условий:

• Входные данные действительно в кодировке ISO-8859-1 / Latin-1 (не Windows-1252 и не уже UTF-8).
• Вы используете PHP 8.2 или более ранней версии, где функция ещё существует.
• Вам нужно быстрое, не требующее зависимостей преобразование Latin-1 → UTF-8.

Избегайте её использования, когда:

• Источник может быть в кодировке Windows-1252 (характерно для текста из Windows / Excel). Windows-1252 использует диапазон 0x80–0x9F для символов, таких как € и фигурные кавычки, которые в ISO-8859-1 не определены — они будут потеряны или искажены. Используйте вместо этого mb_convert_encoding($s, 'UTF-8', 'Windows-1252').
• Вы не знаете точно, в какой кодировке входные данные. Определите или явно укажите кодировку вместо предположений.
• Вы ориентируетесь на PHP 8.3+, где функция полностью удалена.

Современные альтернативы

Поскольку utf8_encode() удалена в PHP 8.3, предпочтительнее использовать функции многобайтовых строк или iconv, которые позволяют явно указать исходную кодировку:

<?php
$latin1 = "\xE9"; // 'é' in ISO-8859-1

// mbstring extension (recommended)
$utf8 = mb_convert_encoding($latin1, 'UTF-8', 'ISO-8859-1');

// iconv extension
$utf8 = iconv('ISO-8859-1', 'UTF-8', $latin1);

echo bin2hex($utf8); // c3a9 in both cases
?>

Оба варианта дают те же два байта (0xC3 0xA9), что и utf8_encode(), но делают исходную кодировку частью вызова — поэтому они также работают для Windows-1252, ISO-8859-15 и десятков других кодировок.

Связанные функции

• utf8_decode() — обратная операция: преобразование UTF-8 обратно в ISO-8859-1.
• json_encode() — выводит данные в UTF-8 и экранирует многобайтовые символы.
• Строки PHP — обзор работы с текстом в PHP.

Заключение

utf8_encode() преобразует текст ISO-8859-1 (Latin-1) в UTF-8, перекодируя каждый байт — превращая однобайтовые символы с диакритическими знаками в их двухбайтовое представление в UTF-8. Функция удобна, но не определяет реальную кодировку входных данных; она признана устаревшей в PHP 8.2 и удалена в PHP 8.3. Для любого нового кода используйте mb_convert_encoding() или iconv(), которые позволяют явно указать исходную кодировку и поддерживают значительно более широкий набор наборов символов.

Практика