htmlentities

    (PHP 4, PHP 5, PHP 7, PHP 8)

    htmlentities — Преобразовывает возможные символы в 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-1ISO8859-1 Западно-Европейская кодировка с набором символов Latin-1.
    ISO-8859-5ISO8859-5 Кириллическая кодировка с набором символов Latin/Cyrillic; применяют редко.
    ISO-8859-15ISO8859-15 Западно-Европейская кодировка с набором символов Latin-9. Добавляет к набору символов Latin-1 кодировки ISO-8859-1 знак евро, французские и финские буквы.
    UTF-8  ASCII-совместимая многобайтовая 8-битная кодировка Unicode.
    cp866ibm866, 866 Кириллическая кодировка, которую применяют в семействе операционных систем DOS.
    cp1251Windows-1251, win-1251, 1251 Кириллическая кодировка, которую применяют в операционных системах Windows.
    cp1252Windows-1252, 1252 Западно-Европейская кодировка, которую применяют в операционных системах Windows.
    KOI8-Rkoi8-ru, koi8r Русская кодировка.
    BIG5950 Кодировка с набором символов Traditional Chinese (Традиционный китайский), которую применяют в основном на Тайване.
    GB2312936 Стандартная национальная кодировка с набором символов Simplified Chinese (Упрощённый китайский).
    BIG5-HKSCS  Кодировка Big5 с расширениями для Гонконга с набором символов Traditional Chinese (Традиционный китайский).
    Shift_JISSJIS, SJIS-win, cp932, 932 Японская кодировка.
    EUC-JPEUCJP, 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>";

    // Выводит: A 'quote' is &lt;b&gt;bold&lt;/b&gt;
    echo htmlentities($str);

    // Выводит: A &#039;quote&#039; is &lt;b&gt;bold&lt;/b&gt;
    echo htmlentities($str, ENT_QUOTES);

    ?>

    Пример #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-кодирует строку
    To Top