htmlspecialchars_decode()

A função htmlspecialchars_decode() faz o inverso de htmlspecialchars(): converte as cinco entidades HTML especiais (&, <, >, ", ') de volta para seus caracteres literais (&, <, >, ", ').

Você normalmente precisa dela quando uma string já foi codificada para exibição segura em HTML e você quer os caracteres brutos novamente — por exemplo, para armazenar o texto original, para comparar com uma entrada não escapada, ou para passar para um sistema que espera marcação literal.

Esta página aborda a sintaxe, o argumento $flags e seu efeito sobre as aspas, a diferença em relação a html_entity_decode(), e uma advertência de segurança que você deve conhecer antes de usá-la.

Sintaxe

htmlspecialchars_decode(string $string, int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401): string

A função retorna a string decodificada. Apenas as entidades produzidas por htmlspecialchars() são convertidas — para o conjunto completo de entidades HTML nomeadas e numéricas, use html_entity_decode().

Nota: o valor padrão de $flags mudou no PHP 8.1 de ENT_COMPAT | ENT_HTML401 para ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401. Os exemplos abaixo se comportam de forma idêntica em ambos.

Exemplo básico

Exemplo de PHP htmlspecialchars_decode()

Neste exemplo, temos uma variável string $html_string contendo algum código HTML com entidades. Usamos a função htmlspecialchars_decode() para converter as entidades HTML nos seus caracteres correspondentes.

A saída deste código será:

<h1>Hello World</h1>

Os caracteres < e > foram restaurados a partir de < e >.

Controlando aspas com $flags

O segundo argumento, $flags, decide quais entidades de aspas são decodificadas. Estes são os valores que você usará com mais frequência:

Um ponto de confusão comum: ENT_COMPAT é o nome frequentemente associado a "somente aspas duplas", mas essa distinção se aplica apenas ao lado da codificação (htmlspecialchars()). Ao decodificar, ' é convertido tanto com ENT_QUOTES quanto com ENT_COMPAT. Para manter as aspas simples codificadas, você deve passar ENT_NOQUOTES.

Como usar PHP htmlspecialchars_decode()?

Neste exemplo, temos uma variável string $html_string contendo algum código HTML com entidades, incluindo uma aspa simples codificada. Usamos a função htmlspecialchars_decode() com a flag ENT_QUOTES para converter as entidades HTML nos seus caracteres correspondentes e para tratar a aspa simples.

A saída deste código será:

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

A flag ENT_QUOTES restaurou a aspa simples em I'm junto com os colchetes angulares.

htmlspecialchars_decode() vs html_entity_decode()

Ambas as funções convertem entidades de volta em caracteres, mas tratam conjuntos diferentes:

• htmlspecialchars_decode() decodifica apenas as cinco entidades criadas por htmlspecialchars(): &, <, >, " e '. É rápida e previsível.
• html_entity_decode() decodifica a tabela completa de entidades HTML, incluindo entidades nomeadas como ©,   e €, bem como referências numéricas.

<?php
$text = "&copy; 2024 &amp; &lt;Acme&gt;";

// Leaves &copy; untouched — it is not one of the five special chars
echo htmlspecialchars_decode($text);   // &copy; 2024 & <Acme>
echo "\n";

// Decodes &copy; too
echo html_entity_decode($text);        // © 2024 & <Acme>
?>

Use htmlspecialchars_decode() quando precisar apenas reverter uma chamada a htmlspecialchars(). Recorra a html_entity_decode() quando o texto puder conter entidades nomeadas como © ou  .

Advertência de segurança

Decodificar converte <script> de volta em uma tag <script> ativa. Nunca decodifique uma string e então a imprima em uma página HTML sem re-escapar, ou você reabrirá uma brecha de cross-site scripting (XSS). Decodifique para armazenamento, comparação ou saída não-HTML — e chame htmlspecialchars() novamente antes de enviar qualquer coisa de volta ao navegador.

Funções relacionadas

• htmlspecialchars() — a contraparte de codificação desta função.
• html_entity_decode() — decodifica todas as entidades HTML, não apenas as cinco especiais.
• htmlentities() — codifica todos os caracteres aplicáveis em entidades.
• strip_tags() — remove tags HTML completamente, em vez de decodificá-las.

Prática