htmlentities()

La fonction PHP htmlentities() convertit chaque caractère possédant une entité HTML nommée en cette entité. C'est le principal outil pour afficher en toute sécurité du texte non fiable — comme une saisie utilisateur provenant d'un formulaire — dans une page HTML, car elle transforme les caractères que le navigateur interpréterait autrement comme du balisage (<, >, &, guillemets) en texte visible inoffensif. C'est ce qui en fait une première ligne de défense contre les attaques de type cross-site scripting (XSS).

Cette page couvre la syntaxe, chacun des quatre paramètres, la différence pratique avec htmlspecialchars(), ainsi que les pièges courants liés à l'encodage et au double-encodage.

Syntaxe

htmlentities(
    string $string,
    int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401,
    ?string $encoding = null,
    bool $double_encode = true
): string

Elle retourne une nouvelle chaîne avec les caractères applicables convertis ; la chaîne originale n'est jamais modifiée.

Remarque : À partir de PHP 8.1, les drapeaux par défaut sont ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401. Sur PHP 8.0 et antérieur, la valeur par défaut était ENT_COMPAT | ENT_HTML401, qui n'encode pas les guillemets simples. Si vous supportez des versions plus anciennes, passez ENT_QUOTES explicitement.

Utilisation de base

Cela produit :

Hello <strong>World</strong>!

Les caractères < et > sont désormais < et >, de sorte que le navigateur les affiche en tant que texte littéral au lieu d'ouvrir une vraie balise <strong>.

Le paramètre $flags — gestion des guillemets

Le deuxième paramètre contrôle la façon dont les guillemets sont traités. Les drapeaux les plus utiles sont :

Utilisez ENT_QUOTES chaque fois que la sortie peut se retrouver dans un attribut HTML entre guillemets simples, car sinon un ' dans les données pourrait sortir de l'attribut.

Sortie :

I'm a paragraph

Le guillemet simple devient '. Avec l'ancienne valeur par défaut ENT_COMPAT, il serait resté un ' littéral.

Le paramètre $encoding

Le troisième paramètre indique à htmlentities() quel jeu de caractères utilise l'entrée, afin de mapper correctement les caractères multi-octets. Définissez-le toujours explicitement à "UTF-8" pour les applications modernes — un encodage incorrect peut corrompre silencieusement la sortie ou, dans les anciennes versions de PHP, retourner une chaîne vide.

Sortie :

Café & «über»

Notez que é, «, ü et » ont chacun été convertis en leur entité nommée — c'est le comportement qui distingue htmlentities() de htmlspecialchars(), qui laisserait ces caractères accentués intacts.

Le paramètre $double_encode

Par défaut (true), htmlentities() ré-encode le & d'une entité existante, donc < devient <. Passez false pour laisser les entités déjà encodées telles quelles — utile lorsqu'une partie de votre chaîne est intentionnellement pré-échappée.

Avec $double_encode à false, les entités existantes passent sans modification :

Hello <strong>World</strong>!

Si vous aviez laissé $double_encode à sa valeur par défaut true, chaque & aurait été ré-échappé en &, produisant Hello <strong>....

htmlentities() vs htmlspecialchars()

C'est le point de confusion le plus courant :

• htmlspecialchars() convertit uniquement les cinq caractères ayant une signification spéciale en HTML : &, <, >, " et '.
• htmlentities() convertit ceux-là plus chaque autre caractère possédant une entité nommée (lettres accentuées, symboles, signes monétaires, etc.).

Pour échapper la sortie de manière sécurisée, htmlspecialchars() est généralement le meilleur choix : elle est plus petite, plus rapide et — tant que vous émettez une page UTF-8 — les caractères accentués s'affichent correctement sans être convertis en entités. Utilisez htmlentities() uniquement lorsque vous avez spécifiquement besoin de convertir chaque caractère mappable en entité, par exemple lors de la génération de contenu pour une cible dont vous ne pouvez pas contrôler le jeu de caractères.

Pour inverser la conversion, utilisez html_entity_decode() ou htmlspecialchars_decode().

Points clés

• htmlentities() retourne une nouvelle chaîne et ne modifie jamais l'original.
• Passez toujours ENT_QUOTES et "UTF-8" explicitement pour une sortie prévisible et sécurisée sur toutes les versions de PHP.
• C'est un filtre de sortie — échappez les données au moment de les afficher, pas au moment de les stocker.
• Pour un échappement HTML typique, préférez htmlspecialchars().

Pratique