(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 и &#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; // <a href='test'>Test</a>
?>Замечание:
Обратите внимание, функция выполняет только описанные преобразования. Для преобразования всех символов вызывают функцию htmlentities().
Замечание:
Когда значение параметра
flagsнеоднозначно, функция применяет следующие правила:
- Значением по умолчанию становится флаг
ENT_NOQUOTES, если одновременно отсутствуют флагиENT_COMPAT,ENT_QUOTESиENT_NOQUOTES.- Если одновременно присутствуют два или более флага
ENT_COMPAT,ENT_QUOTESиENT_NOQUOTES, у флагаENT_QUOTESбудет больший приоритет. Следующим по приоритету будет флагENT_COMPAT.- Флагом по умолчанию становится флаг
ENT_HTML401, если не установили ни одну из константENT_HTML401,ENT_HTML5,ENT_XHTMLиENT_XML1.- Если одновременно установили больше одного флага
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.