htmlentities() vs htmlspecialchars(): a batalha das funções PHP

htmlentities() vs. htmlspecialchars(): guia detalhado com exemplos

Você já se perguntou por que o PHP tem duas funções que fazem, aparentemente, a mesma coisa? htmlentities() e htmlspecialchars() são como dois irmãos gêmeos: parecidos por fora, mas com personalidades diferentes. E a escolha entre eles pode se tornar ou uma habilidade de super-herói, ou uma fonte de dor de cabeça.

Se você já fez essa pergunta no Stack Overflow (e são milhares!), sabe que a resposta nem sempre é óbvia. Hoje vamos entender de uma vez por todas para que serve cada função, quando usar cada uma e como não errar com as codificações.

Vamos lá!

O que essas funções realmente fazem?

Ambas as funções são projetadas para escapar caracteres HTML. Em palavras simples: elas transformam caracteres especiais em suas entidades HTML, para que o navegador os exiba como texto, em vez de interpretá-los como código.

Por exemplo, o caractere < se transforma em <. Isso é criticamente importante para:

\n
• Segurança — proteção contra ataques XSS (cross-site scripting)
\n
• Exibição correta — para que seu texto não "quebre" a marcação HTML
\n

Mas eis o detalhe: htmlspecialchars() funciona apenas com quatro caracteres, enquanto htmlentities() funciona com todas as entidades HTML conhecidas.

htmlspecialchars(): artilharia leve

A função htmlspecialchars() transforma apenas estes caracteres:

\n
• & (e comercial) → &
\n
• " (aspas duplas) → " (se a flag ENT_NOQUOTES não estiver definida)
\n
• ' (aspas simples) → ' (se a flag ENT_QUOTES estiver definida)
\n
• < (menor que) → <
\n
• > (maior que) → >
\n

Este conjunto é suficiente para 99% dos casos. Por quê? Porque apenas esses caracteres têm significado especial na marcação HTML e podem quebrar sua página.

<?php\n$user_input = '<script>alert("XSS")</script>';\necho htmlspecialchars($user_input, ENT_QUOTES, 'UTF-8');\n// Exibirá: &lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;\n?>

htmlentities(): cavalaria pesada

htmlentities() é aquele perfeccionista que transforma em entidades todos os caracteres que possuem um equivalente HTML. Por exemplo, símbolos de moedas (€, £, ¥), sinais matemáticos (∑, ∞, √) e até setinhas (←, ↑).

<?php\n$text = 'Custo: 50€';\necho htmlentities($text, ENT_QUOTES, 'UTF-8');\n// Exibirá: Custo: 50&euro;\n?>

Parece conveniente, certo? Mas há um detalhe — desempenho. htmlentities() é mais lenta porque processa mais caracteres. E se seu site processa milhares de linhas, a diferença se torna perceptível.

Diferença chave: codificação

E é aqui que chegamos ao ponto mais importante. Ambas as funções aceitam um terceiro parâmetro — a codificação. E se você não especificá-la, o PHP usará o valor da diretiva default_charset no php.ini (geralmente UTF-8).

Mas htmlentities() é particularmente sensível à codificação. Se você especificar a codificação errada, a função pode transformar caracteres incorretamente. Por exemplo, com ISO-8859-1, alguns caracteres UTF-8 serão perdidos.

<?php\n// Exemplo ruim: codificação não especificada\necho htmlentities('Olá, mundo!'); // Pode gerar um aviso\n\n// Exemplo bom: sempre especifique a codificação\necho htmlentities('Olá, mundo!', ENT_QUOTES, 'UTF-8');\n?>

Quando usar o quê?