htmlentities()

A função PHP htmlentities() converte todo caractere que possui uma entidade HTML nomeada nessa entidade. É a principal ferramenta para imprimir com segurança textos não confiáveis — como dados enviados pelo usuário em um formulário — dentro de uma página HTML, pois transforma caracteres que o navegador interpretaria como marcação (<, >, &, aspas) em texto visível inofensivo. É isso que a torna a primeira linha de defesa contra cross-site scripting (XSS).

Esta página abrange a sintaxe, cada um dos quatro parâmetros, a diferença prática em relação a htmlspecialchars() e as armadilhas comuns relacionadas a codificação e dupla codificação.

Sintaxe

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

Retorna uma nova string com os caracteres aplicáveis convertidos; a string original nunca é modificada.

Nota: A partir do PHP 8.1, as flags padrão são ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401. No PHP 8.0 e versões anteriores, o padrão era ENT_COMPAT | ENT_HTML401, que não codifica aspas simples. Se você suporta versões mais antigas, passe ENT_QUOTES explicitamente.

Uso básico

A saída é:

Hello <strong>World</strong>!

Os caracteres < e > agora são < e >, portanto o navegador os renderiza como texto literal em vez de abrir uma tag <strong> real.

O parâmetro $flags — tratamento de aspas

O segundo parâmetro controla como as aspas são tratadas. As flags mais úteis são:

Use ENT_QUOTES sempre que a saída puder aparecer dentro de um atributo HTML com aspas simples; caso contrário, um ' nos dados poderia sair do atributo.

Saída:

I'm a paragraph

A aspa simples se torna '. Com o antigo padrão ENT_COMPAT, ela teria permanecido como um ' literal.

O parâmetro $encoding

O terceiro parâmetro informa ao htmlentities() qual conjunto de caracteres a entrada usa para que ele possa mapear corretamente os caracteres multibyte. Sempre defina explicitamente como "UTF-8" em aplicações modernas — uma codificação incompatível pode corromper silenciosamente a saída ou, em versões mais antigas do PHP, retornar uma string vazia.

Saída:

Café & «über»

Observe como é, «, ü e » tornaram-se suas entidades nomeadas — este é o comportamento que distingue htmlentities() de htmlspecialchars(), que deixaria esses caracteres acentuados intocados.

O parâmetro $double_encode

Por padrão (true), htmlentities() recodifica o & em uma entidade existente, portanto < se torna <. Passe false para manter entidades já codificadas intactas — útil quando parte da sua string está intencionalmente pré-escapada.

Com $double_encode definido como false, as entidades existentes passam sem alteração:

Hello <strong>World</strong>!

Se você tivesse mantido $double_encode no padrão true, cada & teria sido reescapado para &, produzindo Hello <strong>....

htmlentities() vs htmlspecialchars()

Este é o ponto de confusão mais comum:

• htmlspecialchars() converte apenas os cinco caracteres com significado especial em HTML: &, <, >, " e '.
• htmlentities() converte esses mais todos os outros caracteres que possuem uma entidade nomeada (letras acentuadas, símbolos, sinais de moeda, entre outros).

Para escapar a saída com segurança, htmlspecialchars() costuma ser a melhor escolha: é menor, mais rápida e — desde que você emita uma página em UTF-8 — os caracteres acentuados são exibidos corretamente sem precisar ser convertidos em entidades. Recorra a htmlentities() somente quando precisar especificamente que todo caractere mapeável para entidade seja convertido, por exemplo ao gerar conteúdo para um destino cujo charset você não pode controlar.

Para reverter a conversão, use html_entity_decode() ou htmlspecialchars_decode().

Pontos principais

• htmlentities() retorna uma nova string e nunca altera a original.
• Sempre passe ENT_QUOTES e "UTF-8" explicitamente para uma saída previsível e segura entre versões do PHP.
• É um filtro de saída — escape os dados ao imprimi-los, não ao armazená-los.
• Para escaping HTML típico, prefira htmlspecialchars().

Prática