array ( 0 => 'index.php', 1 => 'PHP Manual', ), 'head' => array ( 0 => 'UTF-8', 1 => 'ru', ), 'this' => array ( 0 => 'function.htmlspecialchars.php', 1 => 'htmlspecialchars', 2 => 'Преобразовывает специальные символы в HTML-сущности', ), 'up' => array ( 0 => 'ref.strings.php', 1 => 'Функции для работы со строками', ), 'prev' => array ( 0 => 'function.htmlentities.php', 1 => 'htmlentities', ), 'next' => array ( 0 => 'function.htmlspecialchars-decode.php', 1 => 'htmlspecialchars_decode', ), 'alternatives' => array ( ), 'source' => array ( 'lang' => 'ru', 'path' => 'reference/strings/functions/htmlspecialchars.xml', ), 'history' => array ( ), ); $setup["toc"] = $TOC; $setup["toc_deprecated"] = $TOC_DEPRECATED; $setup["parents"] = $PARENTS; manual_setup($setup); contributors($setup); ?>

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-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).

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

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

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

Примеры

Пример #1 Пример преобразования специальных символов в HTML-сущности функцией 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 неоднозначно, функция применяет следующие правила:

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