get_html_translation_table()

La fonction PHP get_html_translation_table() retourne la table de correspondance exacte qu'utilisent htmlspecialchars() et htmlentities() en interne lorsqu'elles convertissent des caractères en entités HTML. Au lieu d'appliquer cette conversion, cette fonction vous remet la table elle-même sous forme d'array associatif, où chaque clé est un caractère brut et chaque valeur est son entité — par exemple '<' correspond à <.

Cette fonction est principalement utile lorsque vous avez besoin d'inspecter quels caractères sont encodés, de personnaliser l'encodage, ou de l'inverser en retournant la table.

Syntaxe

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

Les trois paramètres sont optionnels :

• $table — quelle table retourner. L'une des deux constantes suivantes :
  • HTML_SPECIALCHARS (par défaut) — le petit ensemble utilisé par htmlspecialchars() : &, ", ', <, >.
  • HTML_ENTITIES — l'ensemble complet utilisé par htmlentities(), couvrant des centaines de caractères tels que ©, é et ¡.
• $flags — contrôle la gestion des guillemets et le type de document (voir Drapeaux de guillemets et de document ci-dessous).
• $encoding — l'encodage des caractères (par exemple "UTF-8" ou "ISO-8859-1"). Il détermine les séquences d'octets auxquelles correspondent les caractères de la table retournée.

La fonction retourne un array. Elle ne retourne jamais false, donc il n'y a pas de cas d'erreur à gérer pour des arguments valides.

Retourner la table htmlspecialchars

Avec la table HTML_SPECIALCHARS par défaut, vous obtenez les cinq caractères les plus importants pour une sortie HTML sécurisée :

Sortie :

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

Comme ENT_QUOTES a été passé, le guillemet double (") et le guillemet simple (') apparaissent tous les deux dans la table. Avec le ENT_COMPAT par défaut, le guillemet simple serait absent.

Retourner la table complète htmlentities

Passer HTML_ENTITIES retourne la table complète — plus de 250 entrées, incluant les lettres accentuées et les symboles :

Les premières entrées ressemblent à ceci :

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

C'est la table que htmlentities() parcourt pour convertir le texte. Si vous vous intéressez uniquement aux caractères significatifs pour le balisage, préférez HTML_SPECIALCHARS — elle est plus petite et plus rapide à analyser.

Drapeaux de guillemets et de document

Le paramètre $flags combine un drapeau de style de guillemets avec un drapeau optionnel de type de document en utilisant l'opérateur OR binaire (|). Les valeurs les plus courantes sont :

• ENT_COMPAT — encode les guillemets doubles, laisse les guillemets simples intacts.
• ENT_QUOTES — encode à la fois les guillemets doubles et les guillemets simples.
• ENT_NOQUOTES — laisse les deux types de guillemets intacts.
• ENT_HTML401 — utilise le jeu d'entités HTML 4.01 (le type de document par défaut).
• ENT_HTML5 — utilise le jeu d'entités HTML5.
• ENT_XML1 — utilise le jeu d'entités XML 1.0.
• ENT_XHTML — utilise le jeu d'entités XHTML.

Ici, ENT_QUOTES | ENT_HTML401 demande que les deux types de guillemets soient encodés en utilisant les noms d'entités HTML 4.01. Changer le drapeau de document en ENT_HTML5 modifierait quelques noms d'entités (par exemple, le guillemet simple deviendrait ' au lieu de ').

Utilisation pratique : inverser la table

Une raison pratique courante de récupérer la table est de construire une carte de décodage en inversant les clés et les valeurs avec array_flip(). Vous pouvez ensuite transformer des entités en caractères bruts avec 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>
?>

Pour un décodage courant, vous utiliseriez normalement les fonctions dédiées htmlspecialchars_decode() ou html_entity_decode() — mais la table inversée est pratique lorsque vous avez besoin d'un mappage personnalisé ou partiel.

Quand l'utiliser

Utilisez get_html_translation_table() lorsque vous souhaitez :

• Vérifier exactement quels caractères une combinaison drapeau/encodage donnée va encoder.
• Construire un mappage personnalisé ou inversé que les fonctions d'encodage/décodage standard ne couvrent pas.
• Générer de la documentation ou des tests qui listent toutes les conversions d'entités.

Pour simplement encoder une sortie, utilisez directement htmlspecialchars() ou htmlentities().

Pratique