htmlspecialchars()

Функция htmlspecialchars() преобразует небольшой набор символов, имеющих специальное значение в HTML, в соответствующие HTML-сущности. Её главная задача — безопасность: при выводе данных, введённых пользователем, на веб-страницу предварительный вызов htmlspecialchars() предотвращает интерпретацию этих данных как разметки или скрипта — стандартная защита от атак межсайтового скриптинга (XSS).

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

Синтаксис

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

Функция принимает один обязательный параметр, $string — строку для преобразования — и три необязательных: $flags, $encoding и $double_encode. Она возвращает преобразованную строку.

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

Какие символы преобразуются

Затрагиваются только пять символов. Всё остальное проходит без изменений:

Если вам также нужно кодировать символы с диакритикой, специальные символы и другие символы, не входящие в ASCII, используйте вместо этого htmlentities().

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

Вывод:

Hello <strong>World</strong>!

Теги <strong> преобразованы в <strong> и </strong>. Когда эта строка отправляется в браузер, он отображает буквальный текст <strong>World</strong> вместо того, чтобы отрендерить жирное начертание.

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

Второй параметр, $flags, указывает способ обработки кавычек и используемый тип документа. Наиболее распространённый выбор — ENT_QUOTES, который преобразует как одинарные ('), так и двойные (") кавычки. Это важно всякий раз, когда вы помещаете значение внутрь атрибута HTML, поскольку неэкранированная кавычка может преждевременно закрыть атрибут и внедрить новые.

Вывод:

I'm a paragraph

Одинарная кавычка преобразована в '. Наиболее распространённые значения флагов:

• ENT_QUOTES — преобразует как двойные, так и одинарные кавычки (рекомендуется).
• ENT_COMPAT — преобразует двойные кавычки, оставляя одинарные без изменений.
• ENT_NOQUOTES — оставляет оба вида кавычек без изменений.
• ENT_SUBSTITUTE — заменяет недопустимые последовательности кодовых единиц на � вместо возврата пустой строки.

Параметр $encoding

Третий параметр, $encoding, задаёт кодировку символов входной строки. По умолчанию используется значение параметра INI default_charset (UTF-8 в современных установках). Явное указание кодировки позволяет избежать неожиданностей, если входные данные имеют другую кодировку.

Вывод:

Tom & Jerry

Здесь амперсанд кодируется как &, а PHP интерпретирует входные данные как UTF-8. Если кодировка не соответствует фактическим байтам $string, функция может вернуть пустую строку (или символ замены при установленном ENT_SUBSTITUTE).

Параметр $double_encode

Четвёртый параметр, $double_encode, управляет повторным кодированием уже существующих сущностей. По умолчанию он равен true, поэтому строка, уже содержащая <, превращается в <. Установите значение false, чтобы оставлять уже закодированные сущности нетронутыми — это полезно, когда входные данные уже частично экранированы.

Вывод:

Hello <strong>World</strong>!

Существующие сущности < и > остались без изменений, поскольку $double_encode равен false. При значении по умолчанию true те же входные данные привели бы к Hello <strong>....

Защита от XSS на практике

Наиболее важное применение htmlspecialchars() — экранирование любых данных, которые вы не полностью контролируете: данных из форм, значений строк запросов, записей базы данных, поступивших от пользователей — перед их выводом на страницу:

<?php
$comment = $_GET['comment'] ?? '';   // e.g. "<script>alert('xss')</script>"
echo "<p>" . htmlspecialchars($comment, ENT_QUOTES, "UTF-8") . "</p>";
?>

Тег <script> нейтрализуется в <script>...</script>, поэтому браузер отображает текст вместо его выполнения. Применяйте экранирование в момент вывода, а не при сохранении данных, чтобы исходное значение оставалось доступным для других контекстов.

Обращение преобразования

Чтобы вернуть сущности в исходные символы, используйте htmlspecialchars_decode(). Передайте те же флаги, которые вы использовали при кодировании, чтобы кавычки обрабатывались симметрично.

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

• htmlentities() — аналог htmlspecialchars(), но преобразует все символы, имеющие эквиваленты HTML-сущностей, а не только пять специальных.
• htmlspecialchars_decode() — обратная функция.
• strip_tags() — полностью удаляет HTML- и PHP-теги вместо их экранирования.
• nl2br() — вставляет <br> перед символами новой строки; часто используется после экранирования обычного текста.

Итог

Используйте htmlspecialchars() всякий раз, когда выводите недоверенный текст в HTML. Передавайте ENT_QUOTES и явно указывайте кодировку UTF-8 для предсказуемых и безопасных результатов во всех версиях PHP, выполняйте экранирование в момент вывода и прибегайте к htmlentities() только тогда, когда нужно кодировать все сущности, а не только пять специальных символов.

Практика