Содержание
(PHP 3, PHP 4, PHP 5)
htmlspecialchars — Преобразует специальные символы в HTML сущности
Описание string htmlspecialchars ( string string [, int quote_style [, string charset]] )
В HTML некоторые символы имеют специальное значение и для сохранения своего значения должны быть преобразованы в HTML сущности. Эта функция возвращает строку, над которой проведены некоторые из таких преобразований. Этих преобразований достаточно для большинства задач веб-программирования. Если вам нужно преобразовать все возможные сущности, используйте htmlentities() .
Эта функция полезна при отображении данных, введенных пользователем, которые могут содержать нежелательные HTML тэги, например в форуме или гостевой книге. Необязательный второй аргумент quote_style определяет режим обработки одиночных и двойных кавычек. В режиме по умолчанию, ENT_COMPAT , преобразуются двойные кавычки, одиночные остаются без изменений. В режиме ENT_QUOTES преобразуются и двойные, и одиночные кавычки. а в режиме ENT_NOQUOTES и двойные, и одиночные кавычки остаются без изменений.
Производятся следующие преобразования:
‘&’ (амперсанд) преобразуется в ‘&’
‘"’ (двойная кавычка) преобразуется в ‘"’ when ENT_NOQUOTES is not set.
»’ (одиночная кавычка) преобразуется в »’ только в режиме ENT_QUOTES .
‘ ‘ (знак "больше чем") преобразуется в ‘>’
Пример 1. Пример использования htmlspecialchars()
| = htmlspecialchars ( "Test" , ENT_QUOTES ); echo $new ; // Test ?> |
Обратите внимание, что функция не производит других преобразований кроме описанных выше. Для преобразования всех HTML сущностей используйте htmlentities() . Поддержка необязательного второго аргумента была добавлена в PHP 3.0.17 и PHP 4.0.3.
Необязательный третий аргумент charset определяет кодировку, используемую при преобразовании. По умолчанию используется кодировка ISO-8859-1. Поддержка этого аргумента была добавлена в PHP 4.1.0.
Начиная с PHP 4.3.0 поддерживаются следующие кодировки.
Таблица 1. Поддерживаемые кодировки
| Кодировка | Псевдонимы | Описание |
|---|---|---|
| ISO-8859-1 | ISO8859-1 | Западно-европейская Latin-1 |
| ISO-8859-15 | ISO8859-15 | Западно-европейская Latin-9. Добавляет знак евро, французские и финские буквы к кодировке Latin-1(ISO-8859-1). |
| UTF-8 | 8-битная Unicode, совместимая с ASCII. | |
| cp866 | ibm866, 866 | Кириллическая кодировка, применяемая в DOS. Поддерживается в версии 4.3.2. |
| cp1251 | Windows-1251, win-1251, 1251 | Кириллическая кодировка, применяемая в Windows. Поддерживается в версии 4.3.2. |
| cp1252 | Windows-1252, 1252 | Западно-европейская кодировка, применяемая в Windows. |
| KOI8-R | koi8-ru, koi8r | Русская кодировка. Поддерживается в версии 4.3.2. |
| BIG5 | 950 | Традиционный китайский, применяется в основном на Тайване. |
| GB2312 | 936 | Упрощенный китайский, стандартная национальная кодировка. |
| BIG5-HKSCS | Расширенная Big5, применяемая в Гонг-Конге. | |
| Shift_JIS | SJIS, 932 | Японская кодировка. |
| EUC-JP | EUCJP | Японская кодировка. |
Замечание: Не перечисленные выше кодировки не поддерживаются, и вместо них применяется ISO-8859-1.
(PHP 4, PHP 5, PHP 7)
htmlspecialchars — Преобразует специальные символы в HTML-сущности
Описание
В HTML некоторые символы имеют особый смысл и должны быть представлены в виде HTML-сущностей, чтобы сохранить их значение. Эта функция возвращает строку, над которой проведены эти преобразования. Если вам нужно преобразовать все возможные сущности, используйте htmlentities() .
Если входная строка, переданная в эту функцию и результирующий документ используют одинаковую кодировку символов, то этой функции достаточно, чтобы подготовить данные для вставки в большинство частей HTML документа. Однако, если данные содержат символы, не определенные в кодировке символов результирующего документа и вы ожидаете сохранения этих символов (как числовые или именованные сущности), то вам недостаточно будет этой и htmlentities() функций (которые только преобразуют подстроки с соответствующими сущностями). Необходимо использовать функцию mb_encode_numericentity() .
| Символ | Замена |
|---|---|
| & (амперсанд) | & |
| " (двойные кавычки) | ", если не установлена ENT_NOQUOTES |
| ‘ (одинарные кавычки) | ‘ (для ENT_HTML401 ) или ‘ (для ENT_XML1 , ENT_XHTML или ENT_HTML5 ), но только если установлена ENT_QUOTES |
| (больше) | > |
Список параметров
Битовая маска из нижеуказанных флагов, определяющих режим обработки кавычек, некорректных кодовых последовательностей и используемый тип документа. По умолчанию используется ENT_COMPAT | 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 зависит от используемой версии PHP. В PHP 5.6 и старше, для значения по умолчанию используется конфигурационная опция default_charset. В PHP 5.4 и 5.5 используется UTF-8 по умолчанию. Более ранние версии PHP используют ISO-8859-1.
Хотя этот аргумент является технически необязательным, настоятельно рекомендуется указать правильное значение для вашего кода, если вы используете PHP 5.5 или выше, или если ваша опция конфигурации 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 выключен, то PHP не будет преобразовывать существующие html-сущности. По умолчанию преобразуется все без ограничений.
Возвращаемые значения
Если входная строка string содержит неверную последовательность символов в указанной кодировке encoding , то будет возвращаться пустая строка в случае, если флаги ENT_IGNORE или ENT_SUBSTITUTE не установлены.
Список изменений
| Версия | Описание |
|---|---|
| 5.6.0 | Значение по умолчанию для параметра encoding было изменено на значение конфигурационной опции default_charset. |
| 5.4.0 | Значение по умолчанию для параметра encoding было изменено на UTF-8. |
| 5.4.0 | Добавлены константы ENT_SUBSTITUTE , ENT_DISALLOWED , ENT_HTML401 , ENT_XML1 , ENT_XHTML и ENT_HTML5 . |
| 5.3.0 | Добавлена константа ENT_IGNORE . |
| 5.2.3 | Добавлен параметр double_encode . |
Примеры
Пример #1 Пример использования htmlspecialchars()
Примечания
Обратите внимание, что функция не производит других преобразований, кроме описанных выше. Для преобразования всех HTML-сущностей используйте htmlentities() .
В случае неоднозначного значения flags , применяются следующие правила:
- Если одновременно отсутствуют константы ENT_COMPAT , ENT_QUOTES и ENT_NOQUOTES , по умолчанию будет использоваться ENT_COMPAT .
- Если одновременно присутствуют две или более констант 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_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-код разрыва строки перед каждым переводом строки
(PHP 4, PHP 5, PHP 7)
htmlspecialchars — Преобразует специальные символы в HTML-сущности
Описание
В HTML некоторые символы имеют особый смысл и должны быть представлены в виде HTML сущностей, чтобы сохранить их значение. Эта функция возвращает строку, над которой проведены эти преобразования. Если вам нужно преобразовать все возможные сущности, используйте htmlentities() .
Если входная строка переданная в эту функцию и результирующий документ используют одинаковую кодировку символов, то этой функции достаточно, чтобы подготовить данные для вставки в большинство частей HTML документа. Однако, если данные содержат символы, не определенные в кодировке символов результирующего документа и вы ожидаете сохранения этих символов (как числовые или именованные сущности), то вам недостаточно будет этой и htmlentities() функций (которые только преобразуют подстроки с соответствующими сущностями). Необходимо использовать функцию mb_encode_numericentity() .
Производятся следующие преобразования:
- ‘&’ (амперсанд) преобразуется в ‘&’
- ‘"’ (двойная кавычка) преобразуется в ‘"’ в режиме ENT_NOQUOTES is not set.
- "’" (одиночная кавычка) преобразуется в »’ (или ‘) только в режиме ENT_QUOTES .
- ‘
- ‘>’ (знак "больше чем") преобразуется в ‘>’
Список параметров
Битовая маска из нижеуказанных флагов, определяющих режим обработки кавычек, некорректных кодовых последовательностей и используемый тип документа. По умолчанию используется ENT_COMPAT | 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 зависит от используемой версии PHP. В PHP 5.6 и старше, для значения по умолчанию используется конфигурационная опция default_charset. В PHP 5.4 и 5.5 используется UTF-8 по умолчанию. Более ранние версии PHP используют ISO-8859-1.
Хотя этот аргумент является технически необязательным, настоятельно рекомендуется указать правильное значение для вашего кода, если вы используете PHP 5.5 или выше, или если ваша опция конфигурации 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 выключен, то PHP не будет преобразовывать существующие html-сущности. По умолчанию преобразуется все без ограничений.
Возвращаемые значения
Если входная строка string содержит неверную последовательность символов в указанной кодировке encoding , то будет возвращаться пустая строка в случае, если флаги ENT_IGNORE или ENT_SUBSTITUTE не установлены.
Список изменений
| Версия | Описание |
|---|---|
| 5.6.0 | Значение по умолчанию для параметра encoding было изменено на значение конфигурационной опции default_charset. |
| 5.4.0 | Значение по умолчанию для параметра encoding было изменено на UTF-8. |
| 5.4.0 | Добавлены константы ENT_SUBSTITUTE , ENT_DISALLOWED , ENT_HTML401 , ENT_XML1 , ENT_XHTML и ENT_HTML5 . |
| 5.3.0 | Добавлена константа ENT_IGNORE . |
| 5.2.3 | Добавлен параметр double_encode . |
Примеры
Пример #1 Пример использования htmlspecialchars()
Примечания
Обратите внимание, что функция не производит других преобразований кроме описанных выше. Для преобразования всех HTML сущностей используйте htmlentities() .
Смотрите также
- get_html_translation_table() — Возвращает таблицу преобразований, используемую функциями htmlspecialchars и htmlentities
- htmlspecialchars_decode() — Преобразует специальные HTML-сущности обратно в соответствующие символы
- strip_tags() — Удаляет HTML и PHP-теги из строки
- htmlentities() — Преобразует все возможные символы в соответствующие HTML-сущности
- nl2br() — Вставляет HTML-код разрыва строки перед каждым переводом строки