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

# htmlspecialchars

(PHP 4, PHP 5, PHP 7, PHP 8)

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

### Описание

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

Преобразования
Символ | Замена
--- | ---
`&` (амперсанд) | `&amp;`
`"` (двойные кавычки) | `&quot;`, без флага `ENT_NOQUOTES`
`'` (одинарные кавычки) | `&#039;` для документов стандарта `ENT_HTML401` или `&apos;` для документов стандартов `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` неоднозначно, функция применяет следующие правила:

> - Значением по умолчанию становится флаг `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`.

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

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

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open