htmlspecialchars

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

    htmlspecialchars — Преобразовывает специальные символы в HTML-сущности

    Описание

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

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

    Если у входной строки, которую передали в эту функцию, и результирующего документа одинаковый набор символов, то этой функции хватит, чтобы подготовить входные данные для вставки в бо́льшую часть контекстов HTML-документа. Однако, если данные содержат символы, которые не закодированы в наборе символов результирующего документа, и требуется сохранить эти символы (как числовые или именованные сущности), то как этой функции, так и функции htmlentities() (которые преобразовывают только подстроки, у которых есть эквивалентные именованные сущности), будет недостаточно. Вместо них пользуются функцией mb_encode_numericentity().

    Преобразования
    СимволЗамена
    & (амперсанд)&
    " (двойные кавычки)", без флага ENT_NOQUOTES
    ' (одинарные кавычки)' для документов стандарта ENT_HTML401 или ' для документов стандартов ENT_XML1, ENT_XHTML или ENT_HTML5, но только с флагом ENT_QUOTES
    < (меньше)&lt;
    > (больше)&gt;

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

    string

    Конвертируемая строка (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, ISO-8859-15, UTF-8, cp866, cp1251, cp1252 и KOI8-R практически эквивалентны, при условии, что сама строка string содержит допустимые для заданной кодировки символы, поскольку символы, которые изменяет функция htmlspecialchars(), занимают одинаковые позиции в перечисленных кодировках.

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

    Кодировки, которые поддерживает функция
    КодировкаПсевдонимыОписание
    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).

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

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

    ВерсияОписание
    8.1.0 Значение по умолчанию для параметра flags изменили с ENT_COMPAT на ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.

    Примеры

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

    <?php

    $new     = htmlspecialchars("<a href='test'>Test</a>", ENT_QUOTES);
    echo     $new; // &lt;a href=&#039;test&#039;&gt;Test&lt;/a&gt;

    ?>

    Примечания

    Замечание:

    Обратите внимание, функция выполняет только описанные преобразования. Для преобразования всех символов вызывают функцию htmlentities().

    Замечание:

    Когда значение параметра flags неоднозначно, функция применяет следующие правила:

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

    • get_html_translation_table() - Возвращает таблицу преобразований, используемую функциями htmlspecialchars и htmlentities
    • htmlspecialchars_decode() - Преобразовывает специальные HTML-сущности обратно в символы
    • strip_tags() - Удаляет теги HTML и PHP из строки
    • htmlentities() - Преобразовывает возможные символы в HTML-сущности
    • nl2br() - Вставляет HTML-код разрыва строки перед каждым переводом строки
    To Top