get_html_translation_table()

Функция PHP get_html_translation_table() возвращает точную таблицу поиска, которую htmlspecialchars() и htmlentities() используют внутри при преобразовании символов в HTML-сущности. Вместо того чтобы применять это преобразование, функция возвращает саму таблицу в виде ассоциативного array, где каждый ключ — это необработанный символ, а каждое значение — его сущность. Например, '<' соответствует <.

Это особенно полезно, когда нужно проверить, какие символы кодируются, настроить кодирование или обратить его, перевернув таблицу.

Синтаксис

get_html_translation_table(
    int $table = HTML_SPECIALCHARS,
    int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401,
    string $encoding = "UTF-8"
): array

Все три параметра необязательны:

• $table — какую таблицу вернуть. Одна из двух констант:
  • HTML_SPECIALCHARS (по умолчанию) — небольшой набор, используемый htmlspecialchars(): &, ", ', <, >.
  • HTML_ENTITIES — полный набор, используемый htmlentities(), охватывающий сотни символов, таких как ©, é и ¡.
• $flags — управляет обработкой кавычек и типом документа (см. Флаги кавычек и типа документа ниже).
• $encoding — кодировка символов (например, "UTF-8" или "ISO-8859-1"). Влияет на то, из каких байтовых последовательностей берутся символы в возвращаемой таблице.

Функция возвращает array. Она никогда не возвращает false, поэтому для корректных аргументов нет ошибок, которые нужно обрабатывать.

Возврат таблицы htmlspecialchars

С таблицей HTML_SPECIALCHARS по умолчанию вы получаете пять символов, наиболее важных для безопасного вывода HTML:

Вывод:

Array
(
    ["] => "
    [&] => &
    ['] => '
    [<] => &lt;
    [>] => &gt;
)

Поскольку был передан ENT_QUOTES, в таблице присутствуют и двойная кавычка ("), и одинарная ('). При значении по умолчанию ENT_COMPAT одинарная кавычка отсутствовала бы.

Возврат полной таблицы htmlentities

Передача HTML_ENTITIES возвращает полную таблицу — более 250 записей, включая буквы с диакритическими знаками и символы:

Первые несколько записей выглядят так:

Array
(
    ["] => "
    [&] => &
    ['] => '
    [<] => &lt;
    [>] => &gt;
    [ ] => &nbsp;
    [¡] => &iexcl;
    [¢] => &cent;
    ...
)

Именно эту таблицу htmlentities() перебирает при преобразовании текста. Если вас интересуют только символы, значимые для разметки, предпочтите HTML_SPECIALCHARS — она меньше и быстрее для сканирования.

Флаги кавычек и типа документа

Параметр $flags объединяет флаг стиля кавычек с необязательным флагом типа документа с помощью оператора побитового ИЛИ (|). Наиболее распространённые значения:

• ENT_COMPAT — кодировать двойные кавычки, оставлять одинарные без изменений.
• ENT_QUOTES — кодировать и двойные, и одинарные кавычки.
• ENT_NOQUOTES — оставлять оба типа кавычек без изменений.
• ENT_HTML401 — использовать набор сущностей HTML 4.01 (тип документа по умолчанию).
• ENT_HTML5 — использовать набор сущностей HTML5.
• ENT_XML1 — использовать набор сущностей XML 1.0.
• ENT_XHTML — использовать набор сущностей XHTML.

Здесь ENT_QUOTES | ENT_HTML401 запрашивает кодирование обоих типов кавычек с использованием имён сущностей HTML 4.01. Замена флага типа документа на ENT_HTML5 изменит несколько имён сущностей (например, одинарная кавычка станет ' вместо ').

Практическое применение: обращение таблицы

Распространённая практическая причина получить таблицу — построить карту декодирования, перевернув ключи и значения с помощью array_flip(). Затем можно превратить сущности обратно в символы с помощью strtr():

<?php
$table   = get_html_translation_table(HTML_SPECIALCHARS, ENT_QUOTES);
$flipped = array_flip($table);

echo strtr("&lt;b&gt;Bold &amp; bright&lt;/b&gt;", $flipped);
// Output: <b>Bold & bright</b>
?>

Для повседневного декодирования обычно удобнее использовать специализированные функции htmlspecialchars_decode() или html_entity_decode() — но перевёрнутая таблица пригодится, когда нужно нестандартное или частичное сопоставление.

Когда использовать

Обращайтесь к get_html_translation_table(), когда нужно:

• Проверить, какие именно символы будет кодировать заданная комбинация флагов и кодировки.
• Построить нестандартное или обратное сопоставление, которое стандартные функции кодирования/декодирования не охватывают.
• Сформировать документацию или тесты, перечисляющие все преобразования сущностей.

Для простого кодирования вывода используйте htmlspecialchars() или htmlentities() напрямую.

Практика