Преобразовывает возможные символы в HTML-сущности

Описание

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

Функция работает идентично функции htmlspecialchars(), за исключением того, что функция htmlentities() преобразовывает в HTML-сущности каждый символ, для которого в таблице перевода содержится эквивалентная HTML-сущность. Таблицу перевода, которую использует эта функция и которая зависит от констант, которые передали в параметр flags, возвращает функция get_html_translation_table().

Функция html_entity_decode() выполняет обратное преобразование — декодирует HTML-сущности в символы.

Список параметров

string

Входная строка.

flags

Битовая маска из следующих флагов, которые определяют, как обрабатывать кавычки, неправильные последовательности кодовых единиц и тип документа. Маска по умолчанию: ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.

**Доступные константы параметра `flags`**
Название константы	Описание
`ENT_COMPAT`	Преобразовывает двойные кавычки, одинарные кавычки не изменяются.
`ENT_QUOTES`	Преобразовывает как двойные, так и одинарные кавычки.
`ENT_NOQUOTES`	Оставляет без изменения как двойные, так и одинарные кавычки.
`ENT_IGNORE`	Без предупреждения отбрасывает неправильные последовательности кодовых единиц вместо возврата пустой строки. Передача этого флага не рекомендуется, поскольку это » небезопасно.
`ENT_SUBSTITUTE`	Заменяет неправильные последовательности кодовых единиц символом замены Юникода вместо возврата пустой строки: U+FFFD для строк в кодировке UTF-8 и &#FFFD; для строк в других кодировках.
`ENT_DISALLOWED`	Заменяет неверные кодовые точки для заданного типа документа символом замены юникода U+FFFD для строк в кодировке UTF-8 или &#FFFD; для строк в других кодировках вместо того, чтобы оставлять всё как есть. Это бывает полезно для правильного оформления XML-документов, в которые встроили внешнее содержимое.
`ENT_HTML401`	Обрабатывает код по правилам стандарта HTML 4.01.
`ENT_XML1`	Обрабатывает код по правилам стандарта XML 1.
`ENT_XHTML`	Обрабатывает код по правилам стандарта XHTML.
`ENT_HTML5`	Обрабатывает код по правилам стандарта HTML 5.

encoding

Необязательный аргумент, который определяет кодировку для преобразования символов.

Функция примет за значение по умолчанию для параметра encoding значение опции конфигурации default_charset, если параметр опустили.

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

Функция поддерживает следующие кодировки:

**Кодировки, которые поддерживает функция**
Кодировка	Псевдонимы	Описание
ISO-8859-1	ISO8859-1	Западно-Европейская кодировка с набором символов Latin-1.
ISO-8859-5	ISO8859-5	Кириллическая кодировка с набором символов Latin/Cyrillic; применяют редко.
ISO-8859-15	ISO8859-15	Западно-Европейская кодировка с набором символов Latin-9. Добавляет к набору символов Latin-1 кодировки ISO-8859-1 знак евро, французские и финские буквы.
UTF-8		ASCII-совместимая многобайтовая 8-битная кодировка Unicode.
cp866	ibm866, 866	Кириллическая кодировка, которую применяют в семействе операционных систем DOS.
cp1251	Windows-1251, win-1251, 1251	Кириллическая кодировка, которую применяют в операционных системах Windows.
cp1252	Windows-1252, 1252	Западно-Европейская кодировка, которую применяют в операционных системах Windows.
KOI8-R	koi8-ru, koi8r	Русская кодировка.
BIG5	950	Кодировка с набором символов Traditional Chinese (Традиционный китайский), которую применяют в основном на Тайване.
GB2312	936	Стандартная национальная кодировка с набором символов Simplified Chinese (Упрощённый китайский).
BIG5-HKSCS		Кодировка Big5 с расширениями для Гонконга с набором символов Traditional Chinese (Традиционный китайский).
Shift_JIS	SJIS, SJIS-win, cp932, 932	Японская кодировка.
EUC-JP	EUCJP, eucJP-win	Японская кодировка.
MacRoman		Кодировка, которую использовала операционная система Mac OS.
`''`		Пустая строка активирует режим определения кодировки из файла скрипта (Zend multibyte), директивы default_charset и текущей локали (смотрите описание функций nl_langinfo() и setlocale()), в перечисленном порядке. Не рекомендуется использовать.

Замечание: Другие кодировки функция не распознаёт. Вместо других кодировок функция будет использовать кодировку по умолчанию и выдаст предупреждение.

double_encode

Когда параметр double_encode отключён, PHP не будет кодировать существующие HTML-сущности. По умолчанию функция преобразовывает каждый символ.

Возвращаемые значения

Функция возвращает преобразованную строку.

Функция вернёт пустую строку, если входная строка string содержит недопустимую для кодировки encoding последовательность кодовых единиц, если только не установили флаг ENT_IGNORE или ENT_SUBSTITUTE.

Список изменений

Версия	Описание
8.1.0	Значение по умолчанию параметра `flags` изменили с `ENT_COMPAT` на `ENT_QUOTES` \| `ENT_SUBSTITUTE` \| `ENT_HTML401`.
8.0.0	Параметр `encoding` теперь принимает значение null.

Примеры

Пример #1 Пример использования функции htmlentities()

<?php

$str = "A 'quote' is <b>bold</b>";

echo htmlentities($str);
echo "\n\n";
echo htmlentities($str, ENT_COMPAT);

?>

Результат выполнения приведённого примера:

A &#039;quote&#039; is &lt;b&gt;bold&lt;/b&gt;

A 'quote' is &lt;b&gt;bold&lt;/b&gt;

Пример #2 Передача флага ENT_IGNORE

<?php

$str = "\x8F!!!";

// Выводит пустую строку
echo htmlentities($str, ENT_QUOTES, "UTF-8");

// Выводит "!!!"
echo htmlentities($str, ENT_QUOTES | ENT_IGNORE, "UTF-8");

?>

Смотрите также

html_entity_decode() - Преобразовывает HTML-сущности в символы
get_html_translation_table() - Возвращает таблицу преобразований, используемую функциями htmlspecialchars и htmlentities
htmlspecialchars() - Преобразовывает специальные символы в HTML-сущности
nl2br() - Вставляет HTML-код разрыва строки перед каждым переводом строки
urlencode() - URL-кодирует строку