html_entity_decode()

PHP-функция html_entity_decode() преобразует HTML-сущности (такие как <, & или ©) обратно в соответствующие символы (<, &, ©). Она является обратной к htmlentities() и используется в тех случаях, когда нужно превратить уже закодированный HTML обратно в читаемый текст — например, при чтении данных, сохранённых в закодированном виде, или при обработке вывода системы, которая экранировала свой HTML.

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

Синтаксис

html_entity_decode(
    string $string,
    int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401,
    ?string $encoding = null
): string

Функция возвращает декодированную строку. Начиная с PHP 8.1, значение $flags по умолчанию — ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401; в более старых версиях по умолчанию использовалось ENT_COMPAT | ENT_HTML401.

Базовый пример

Сущности < и > преобразуются обратно в < и >, поэтому вывод будет:

<h1>Hello World</h1>

Управление кавычками с помощью $flags

Параметр $flags определяет, как обрабатываются одиночные и двойные кавычки:

Добавьте ENT_HTML401, ENT_HTML5, ENT_XML1 или ENT_XHTML, чтобы выбрать набор сущностей, а ENT_SUBSTITUTE/ENT_IGNORE — для управления обработкой недопустимых последовательностей байтов. Используйте ENT_QUOTES, если входные данные могут содержать закодированные одиночные кавычки (' / '):

С флагом ENT_QUOTES восстанавливаются как теги, так и закодированная одиночная кавычка:

<p>I'm a paragraph</p>

Указание кодировки символов

Третий параметр, $encoding, сообщает PHP, как интерпретировать входные байты. По умолчанию он использует настройку default_charset из php.ini. Передавайте его явно, если не можете полагаться на это значение по умолчанию — чаще всего "UTF-8":

Флаг ENT_HTML5 позволяет PHP распознавать полный набор именованных сущностей HTML5, поэтому é и & декодируются в:

Café & Co.

Безопасность: не декодируйте перед выводом

html_entity_decode() является противоположностью экранирования. Декодирование пользовательского контента с последующим выводом на страницу возвращает любые теги <script> или атрибуты, которые были удалены экранированием, открывая уязвимость XSS. Декодируйте данные только тогда, когда вам нужны исходные символы для целей, не связанных с HTML (логирование, сравнение, создание текстовой версии, генерация PDF и т. д.). При выводе в HTML оставляйте данные экранированными.

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

• htmlentities() — обратная функция: преобразует символы в HTML-сущности.
• htmlspecialchars() — экранирует только пять специальных HTML-символов (<, >, &, ", ').
• htmlspecialchars_decode() — отменяет действие htmlspecialchars(); работает быстрее, чем html_entity_decode(), если нужно вернуть только эти пять символов.

html_entity_decode() работает с полным набором именованных сущностей, поэтому используйте её, когда входные данные могут содержать сущности вроде © или é; обращайтесь к htmlspecialchars_decode(), когда вывод был сформирован исключительно через htmlspecialchars().

Практика