html_entity_decode()

A função PHP html_entity_decode() converte entidades HTML (como <, & ou ©) de volta para os seus caracteres correspondentes (<, &, ©). É o inverso de htmlentities(), e é a função utilizada quando você precisa transformar HTML já codificado de volta em texto legível — por exemplo, ao ler dados que foram armazenados em formato codificado, ou ao processar a saída de um sistema que escapou o seu HTML.

Esta página explica a sintaxe, cada parâmetro, os flags que controlam como as aspas são tratadas, e os erros comuns (especialmente em relação à segurança).

Sintaxe

html_entity_decode(
    string $string,
    int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401,
    ?string $encoding = null
): string

A função retorna a string decodificada. Desde o PHP 8.1, o padrão para $flags é ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401; versões mais antigas usavam ENT_COMPAT | ENT_HTML401 como padrão.

Exemplo básico

As entidades < e > são convertidas de volta para < e >, portanto a saída é:

<h1>Hello World</h1>

Controlando aspas com $flags

O parâmetro $flags determina como as aspas simples e duplas são tratadas:

Adicione ENT_HTML401, ENT_HTML5, ENT_XML1 ou ENT_XHTML para escolher o conjunto de entidades, e ENT_SUBSTITUTE/ENT_IGNORE para controlar como sequências de bytes inválidas são tratadas. Use ENT_QUOTES quando a entrada pode conter aspas simples codificadas (' / '):

Com ENT_QUOTES, tanto as tags quanto a aspa simples codificada são restauradas:

<p>I'm a paragraph</p>

Especificando a codificação de caracteres

O terceiro parâmetro, $encoding, informa ao PHP como interpretar os bytes de entrada. O padrão é a sua configuração ini default_charset. Passe-o explicitamente quando não puder confiar nesse padrão — na maioria das vezes "UTF-8":

ENT_HTML5 permite que o PHP reconheça o conjunto completo de entidades HTML5 nomeadas, portanto é e & são decodificados para:

Café & Co.

Segurança: não decodifique antes de exibir

html_entity_decode() é o oposto do escape. Decodificar conteúdo fornecido pelo usuário e depois imprimi-lo em uma página reintroduz quaisquer tags <script> ou atributos que o escape havia removido, abrindo uma brecha XSS. Decodifique apenas quando precisar dos caracteres brutos para fins não relacionados ao HTML (registro de logs, comparação, geração de versão em texto simples, criação de um PDF, etc.). Ao exibir em HTML, mantenha os dados escapados.

Funções relacionadas

• htmlentities() — o inverso: converte caracteres em entidades HTML.
• htmlspecialchars() — escapa apenas os cinco caracteres especiais do HTML (<, >, &, ", ').
• htmlspecialchars_decode() — inverte htmlspecialchars(); mais rápido que html_entity_decode() quando você só precisa recuperar esses cinco caracteres.

html_entity_decode() lida com o conjunto completo de entidades nomeadas, portanto use-a quando a entrada pode conter entidades como © ou é; use htmlspecialchars_decode() quando a saída foi produzida apenas com htmlspecialchars().

Prática