htmlentities()

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

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

Синтаксис

htmlentities(
    string $string,
    int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401,
    ?string $encoding = null,
    bool $double_encode = true
): string

Функция возвращает новую строку с преобразованными символами; исходная строка никогда не изменяется.

Примечание: Начиная с PHP 8.1 флаги по умолчанию — ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401. В PHP 8.0 и более ранних версиях по умолчанию использовалось ENT_COMPAT | ENT_HTML401, которое не кодирует одиночные кавычки. Если вы поддерживаете более старые версии, передавайте ENT_QUOTES явно.

Базовое использование

Вывод:

Hello <strong>World</strong>!

Символы < и > теперь стали < и >, поэтому браузер отображает их как обычный текст, а не открывает настоящий тег <strong>.

Параметр $flags — обработка кавычек

Второй параметр управляет обработкой кавычек. Наиболее полезные флаги:

Используйте ENT_QUOTES всегда, когда вывод может оказаться внутри HTML-атрибута в одинарных кавычках — иначе символ ' в данных может нарушить атрибут.

Вывод:

I'm a paragraph

Одиночная кавычка превращается в '. При старом значении по умолчанию ENT_COMPAT она осталась бы литеральным символом '.

Параметр $encoding

Третий параметр сообщает htmlentities(), какую кодировку использует входная строка, чтобы функция могла правильно преобразовывать многобайтовые символы. Всегда явно указывайте "UTF-8" для современных приложений — несоответствие кодировок может незаметно исказить вывод или, в старых версиях PHP, вернуть пустую строку.

Вывод:

Café & «über»

Обратите внимание, что é, «, ü и » превратились в именованные сущности — это поведение отличает htmlentities() от htmlspecialchars(), которая оставила бы эти символы с диакритикой без изменений.

Параметр $double_encode

По умолчанию (true) htmlentities() повторно кодирует & в существующей сущности, превращая < в <. Передайте false, чтобы уже закодированные сущности оставались без изменений — это полезно, когда часть строки намеренно предварительно экранирована.

При $double_encode, равном false, существующие сущности передаются без изменений:

Hello <strong>World</strong>!

Если бы вы оставили $double_encode в значении по умолчанию true, каждый символ & был бы повторно экранирован в &, что дало бы Hello <strong>....

htmlentities() vs htmlspecialchars()

Это наиболее распространённый источник путаницы:

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

Для безопасного экранирования вывода htmlspecialchars() обычно является лучшим выбором: она меньше, быстрее и — при условии вывода страницы в UTF-8 — символы с диакритикой корректно отображаются сами по себе без преобразования в сущности. Обращайтесь к htmlentities() только тогда, когда вам специально нужно преобразовать каждый символ, отображаемый в сущность, например при генерации контента для цели, кодировку которой вы не можете контролировать.

Для обратного преобразования используйте html_entity_decode() или htmlspecialchars_decode().

Основные положения

• htmlentities() возвращает новую строку и никогда не изменяет исходную.
• Всегда явно передавайте ENT_QUOTES и "UTF-8" для предсказуемого и безопасного вывода во всех версиях PHP.
• Это выходной фильтр — экранируйте данные при выводе, а не при сохранении.
• Для типичного HTML-экранирования предпочтительнее htmlspecialchars().

Практика