get_html_translation_table()

La funzione PHP get_html_translation_table() restituisce la tabella di ricerca esatta che htmlspecialchars() e htmlentities() utilizzano internamente quando convertono i caratteri in entità HTML. Invece di applicare quella conversione, questa funzione ti consegna la tabella stessa come array associativo, dove ogni chiave è un carattere grezzo e ogni valore è la sua entità — per esempio '<' viene mappato a <.

Questa funzione è utile principalmente quando hai bisogno di ispezionare quali caratteri vengono codificati, personalizzare la codifica, o invertirla capovolgendo la tabella.

Sintassi

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

Tutti e tre i parametri sono opzionali:

• $table — quale tabella restituire. Uno di due costanti:
  • HTML_SPECIALCHARS (predefinita) — il piccolo insieme usato da htmlspecialchars(): &, ", ', <, >.
  • HTML_ENTITIES — l'insieme completo usato da htmlentities(), che copre centinaia di caratteri come ©, é e ¡.
• $flags — controlla la gestione delle virgolette e il tipo di documento (vedi Flag per virgolette e tipo di documento qui sotto).
• $encoding — la codifica dei caratteri (per esempio "UTF-8" o "ISO-8859-1"). Influenza le sequenze di byte da cui i caratteri nella tabella restituita vengono mappati.

La funzione restituisce un array. Non restituisce mai false, quindi non c'è un caso di errore da gestire per argomenti validi.

Restituzione della tabella htmlspecialchars

Con la tabella predefinita HTML_SPECIALCHARS si ottengono i cinque caratteri più importanti per un output HTML sicuro:

Output:

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

Poiché è stato passato ENT_QUOTES, sia la virgoletta doppia (") che quella singola (') compaiono nella tabella. Con il valore predefinito ENT_COMPAT, la virgoletta singola sarebbe assente.

Restituzione della tabella completa htmlentities

Passando HTML_ENTITIES si ottiene la tabella completa — oltre 250 voci, incluse lettere accentate e simboli:

Le prime voci appaiono così:

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

Questa è la tabella che htmlentities() scorre per convertire il testo. Se ti interessano solo i caratteri significativi per il markup, preferisci HTML_SPECIALCHARS — è più piccola e più veloce da scorrere.

Flag per virgolette e tipo di documento

Il parametro $flags combina un flag per lo stile delle virgolette con un flag opzionale per il tipo di documento usando l'operatore OR bit a bit (|). I valori più comuni sono:

• ENT_COMPAT — codifica le virgolette doppie, lascia intatte le virgolette singole.
• ENT_QUOTES — codifica sia le virgolette doppie che quelle singole.
• ENT_NOQUOTES — lascia intatti entrambi i tipi di virgolette.
• ENT_HTML401 — utilizza il set di entità HTML 4.01 (tipo di documento predefinito).
• ENT_HTML5 — utilizza il set di entità HTML5.
• ENT_XML1 — utilizza il set di entità XML 1.0.
• ENT_XHTML — utilizza il set di entità XHTML.

Qui ENT_QUOTES | ENT_HTML401 richiede che entrambi i tipi di virgolette vengano codificati usando i nomi delle entità HTML 4.01. Cambiando il flag del documento in ENT_HTML5 si modificherebbero alcuni nomi di entità (per esempio la virgoletta singola diventerebbe ' invece di ').

Uso pratico: inversione della tabella

Un motivo pratico comune per ottenere la tabella è costruire una mappa di decodifica capovolgendo chiavi e valori con array_flip(). È quindi possibile riconvertire le entità in caratteri grezzi con 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>
?>

Per la decodifica quotidiana si ricorre normalmente alle funzioni dedicate htmlspecialchars_decode() o html_entity_decode() — ma la tabella capovolta è utile quando si ha bisogno di una mappatura personalizzata o parziale.

Quando utilizzarla

Ricorri a get_html_translation_table() quando vuoi:

• Verificare esattamente quali caratteri una determinata combinazione di flag/codifica codificherà.
• Costruire una mappatura personalizzata o invertita che le funzioni standard di codifica/decodifica non coprono.
• Generare documentazione o test che elencano ogni conversione di entità.

Per codificare semplicemente l'output, usa direttamente htmlspecialchars() o htmlentities().

Pratica