get_html_translation_table()

A função PHP get_html_translation_table() retorna a tabela de consulta exata que htmlspecialchars() e htmlentities() usam internamente ao converter caracteres em entidades HTML. Em vez de aplicar essa conversão, esta função fornece a própria tabela como um array associativo, onde cada chave é um caractere bruto e cada valor é sua entidade — por exemplo, '<' mapeia para <.

Isso é útil principalmente quando você precisa inspecionar quais caracteres são codificados, personalizar a codificação ou inverter a conversão trocando as chaves e valores da tabela.

Sintaxe

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

Todos os três parâmetros são opcionais:

• $table — qual tabela retornar. Uma de duas constantes:
  • HTML_SPECIALCHARS (padrão) — o pequeno conjunto usado por htmlspecialchars(): &, ", ', <, >.
  • HTML_ENTITIES — o conjunto completo usado por htmlentities(), cobrindo centenas de caracteres como ©, é e ¡.
• $flags — controla o tratamento de aspas e o tipo de documento (consulte Flags de aspas e documento abaixo).
• $encoding — a codificação de caracteres (por exemplo, "UTF-8" ou "ISO-8859-1"). Afeta as sequências de bytes das quais os caracteres na tabela retornada mapeiam.

A função retorna um array. Ela nunca retorna false, portanto não há caso de erro para tratar com argumentos válidos.

Retornando a tabela do htmlspecialchars

Com a tabela padrão HTML_SPECIALCHARS, você obtém os cinco caracteres mais importantes para uma saída HTML segura:

Saída:

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

Como ENT_QUOTES foi passado, tanto as aspas duplas (") quanto as aspas simples (') aparecem na tabela. Com o padrão ENT_COMPAT, as aspas simples não estariam presentes.

Retornando a tabela completa do htmlentities

Passando HTML_ENTITIES retorna a tabela completa — mais de 250 entradas, incluindo letras acentuadas e símbolos:

As primeiras entradas ficam assim:

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

Esta é a tabela que htmlentities() percorre para converter texto. Se você se preocupa apenas com os caracteres significativos para a marcação, prefira HTML_SPECIALCHARS — ela é menor e mais rápida de percorrer.

Flags de aspas e documento

O parâmetro $flags combina uma flag de estilo de aspas com uma flag opcional de tipo de documento usando o operador OR bit a bit (|). Os valores mais comuns são:

• ENT_COMPAT — codifica aspas duplas, deixa aspas simples intactas.
• ENT_QUOTES — codifica tanto aspas duplas quanto simples.
• ENT_NOQUOTES — deixa ambos os tipos de aspas intactos.
• ENT_HTML401 — usa o conjunto de entidades HTML 4.01 (o tipo de documento padrão).
• ENT_HTML5 — usa o conjunto de entidades HTML5.
• ENT_XML1 — usa o conjunto de entidades XML 1.0.
• ENT_XHTML — usa o conjunto de entidades XHTML.

Aqui, ENT_QUOTES | ENT_HTML401 solicita que ambos os tipos de aspas sejam codificados usando os nomes de entidades HTML 4.01. Mudar a flag de documento para ENT_HTML5 alteraria alguns nomes de entidades (por exemplo, aspas simples tornam-se ' em vez de ').

Uso prático: invertendo a tabela

Um motivo prático comum para obter a tabela é construir um mapa de decodificação trocando chaves e valores com array_flip(). Você pode então converter entidades de volta em caracteres brutos com 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>
?>

Para decodificação cotidiana, você normalmente usaria as funções dedicadas htmlspecialchars_decode() ou html_entity_decode() — mas a tabela invertida é útil quando você precisa de um mapeamento personalizado ou parcial.

Quando usar

Use get_html_translation_table() quando quiser:

• Auditar exatamente quais caracteres uma determinada combinação de flag/codificação irá codificar.
• Construir um mapeamento personalizado ou invertido que as funções padrão de codificação/decodificação não cobrem.
• Gerar documentação ou testes que listem todas as conversões de entidades.

Para simplesmente codificar a saída, use htmlspecialchars() ou htmlentities() diretamente.

Prática