(PHP 4, PHP 5, PHP 7, PHP 8)
htmlspecialchars — Преобразует специальные символы в HTML-сущности
$string
,$flags
= ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401,$encoding
= null
,$double_encode
= true
В HTML некоторые символы имеют особый смысл и должны быть представлены в виде HTML-сущностей, чтобы сохранить их значение. Эта функция возвращает строку, над которой проведены эти преобразования. Если вам нужно преобразовать все возможные сущности, используйте htmlentities().
Если входная строка, переданная в эту функцию и результирующий документ используют одинаковую кодировку символов, то этой функции достаточно, чтобы подготовить данные для вставки в большинство частей HTML-документа. Однако, если данные содержат символы, не определённые в кодировке символов результирующего документа и вы ожидаете сохранения этих символов (как числовые или именованные сущности), то вам недостаточно будет этой и htmlentities() функций (которые только преобразуют подстроки с соответствующими сущностями). Необходимо использовать функцию mb_encode_numericentity().
Символ | Замена |
---|---|
& (амперсанд) |
& |
" (двойные кавычки) |
" , если не установлена ENT_NOQUOTES |
' (одинарные кавычки) |
' (для ENT_HTML401 ) или ' (для
ENT_XML1 , ENT_XHTML или
ENT_HTML5 ), но только если установлена
ENT_QUOTES
|
< (меньше) |
< |
> (больше) |
> |
string
Конвертируемая строка (string).
flags
Битовая маска из нижеуказанных флагов, определяющих режим обработки
кавычек, некорректных кодовых последовательностей и используемый
тип документа. По умолчанию используется
ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401
.
Название константы | Описание |
---|---|
ENT_COMPAT |
Преобразует двойные кавычки, одинарные кавычки не изменяются. |
ENT_QUOTES |
Преобразует как двойные, так и одинарные кавычки. |
ENT_NOQUOTES |
Оставляет без изменения как двойные, так и одинарные кавычки. |
ENT_IGNORE |
Без всяких уведомительных сообщений отбрасывает некорректные кодовые последовательности вместо возврата пустой строки. Использование этого флага не рекомендуется, так как это может привести к » негативным последствиям, связанным с безопасностью. |
ENT_SUBSTITUTE |
Заменяет некорректные кодовые последовательности символом замены Юникода U+FFFD в случае использования UTF-8 или � при использовании другой кодировки, вместо возврата пустой строки. |
ENT_DISALLOWED |
Заменяет неверные коды символов для заданного типа документа символом замены юникода U+FFFD (UTF-8) или � (при использовании другой кодировки) вместо того, чтобы оставлять все как есть. Это может быть полезно, например, для того, чтобы убедиться в формальной правильности 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 | 8-битная Unicode, совместимая с ASCII. | |
cp866 | ibm866, 866 | Кириллическая кодировка, применяемая в DOS. |
cp1251 | Windows-1251, win-1251, 1251 | Кириллическая кодировка, применяемая в Windows. |
cp1252 | Windows-1252, 1252 | Западно-европейская кодировка, применяемая в Windows. |
KOI8-R | koi8-ru, koi8r | Русская кодировка. |
BIG5 | 950 | Традиционный китайский, применяется в основном на Тайване. |
GB2312 | 936 | Упрощённый китайский, стандартная национальная кодировка. |
BIG5-HKSCS | Расширенная Big5, применяемая в Гонконге. | |
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 Пример использования htmlspecialchars()
<?php
$new = htmlspecialchars("<a href='test'>Test</a>", ENT_QUOTES);
echo $new; // <a href='test'>Test</a>
?>
Замечание:
Обратите внимание, что функция не производит других преобразований, кроме описанных выше. Для преобразования всех HTML-сущностей используйте htmlentities().
Замечание:
В случае неоднозначного значения
flags
, применяются следующие правила:
- Если одновременно отсутствуют константы
ENT_COMPAT
,ENT_QUOTES
иENT_NOQUOTES
, по умолчанию будет использоватьсяENT_NOQUOTES
.- Если одновременно присутствуют две или более констант
ENT_COMPAT
,ENT_QUOTES
иENT_NOQUOTES
,ENT_QUOTES
будет иметь больший приоритет. Следующая по приоритету будетENT_COMPAT
.- Если нет ни одной из констант
ENT_HTML401
,ENT_HTML5
,ENT_XHTML
иENT_XML1
, по умолчанию будет использоватьсяENT_HTML401
.- Если одновременно присутствуют две или более констант
ENT_HTML401
,ENT_HTML5
,ENT_XHTML
,ENT_XML1
, то приоритет будет таким:ENT_HTML5
, потомENT_XHTML
,ENT_XML1
, а потомENT_HTML401
.- Если одновременно присутствуют две или более констант
ENT_DISALLOWED
,ENT_IGNORE
,ENT_SUBSTITUTE
, высшим приоритетом будет обладатьENT_IGNORE
, а следующая за нейENT_SUBSTITUTE
.