htmlspecialchars

(PHP 4, PHP 5, PHP 7)

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

Описание

htmlspecialchars ( string $string , int $flags = ENT_COMPAT , string|null $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_COMPAT | ENT_HTML401.

Доступные значения параметра flags
Название константы Описание
ENT_COMPAT Преобразует двойные кавычки, одинарные кавычки не изменяются.
ENT_QUOTES Преобразует как двойные, так и одинарные кавычки.
ENT_NOQUOTES Оставляет без изменения как двойные, так и одинарные кавычки.
ENT_IGNORE Без всяких уведомительных сообщений отбрасывает некорректные кодовые последовательности вместо возврата пустой строки. Использование этого флага не рекомендуется, так как это может привести к » негативным последствиям, связанным с безопасностью.
ENT_SUBSTITUTE Заменяет некорреткные кодовые последовательности символом замены Юникода U+FFFD в случае использования UTF-8 или &#xFFFD; при использовании другой кодировки, вместо возврата пустой строки.
ENT_DISALLOWED Заменяет неверные коды символов для заданного типа документа символом замены юникода U+FFFD (UTF-8) или &#xFFFD; (при использовании другой кодировки) вместо того, чтобы оставлять все как есть. Это может быть полезно, например, для того, чтобы убедиться в формальной правильности 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 не установлены.

Примеры

Пример #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;
?>

Примечания

Замечание:

Обратите внимание, что функция не производит других преобразований, кроме описанных выше. Для преобразования всех 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.

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

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

© 2008—2024 «phpm.ru | Документация и сервисы»       PHP | MySQL | Smarty | PEAR | PHP-GTK | Типограф | Сокращатель ссылок