htmlspecialchars()

A função htmlspecialchars() converte os poucos caracteres que têm um significado especial em HTML nas suas entidades HTML correspondentes. Seu principal objetivo é a segurança: ao exibir dados fornecidos pelo usuário em uma página web, passá-los por htmlspecialchars() primeiro impede que esses dados sejam interpretados como marcação ou script — a defesa padrão contra ataques de cross-site scripting (XSS).

Esta página aborda a sintaxe da função, cada um de seus parâmetros com exemplos executáveis, os cinco caracteres que ela afeta, como ela difere de funções relacionadas e como revertê-la com segurança.

Sintaxe

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

A função aceita um parâmetro obrigatório, $string — a string a ser convertida — e três parâmetros opcionais: $flags, $encoding e $double_encode. Ela retorna a string convertida.

Nota sobre o valor padrão de flags. A partir do PHP 8.1, o valor padrão de $flags é ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, que codifica tanto aspas simples quanto duplas. No PHP 8.0 e anteriores, o padrão era ENT_COMPAT, que deixava as aspas simples intactas. Se você suporta versões mais antigas, sempre passe ENT_QUOTES explicitamente para que o comportamento seja previsível.

Quais caracteres são convertidos

Apenas cinco caracteres são afetados. Todo o restante passa sem alteração:

Se você também precisar codificar letras acentuadas, símbolos e outros caracteres não-ASCII, use htmlentities().

Exemplo básico

Saída:

Hello <strong>World</strong>!

As tags <strong> foram convertidas para <strong> e </strong>. Quando essa string é enviada ao navegador, ela exibe o texto literal <strong>World</strong> em vez de renderizar a marcação em negrito.

O parâmetro $flags: tratamento de aspas

O segundo parâmetro, $flags, especifica como lidar com aspas e qual tipo de documento usar. A escolha mais comum é ENT_QUOTES, que converte tanto aspas simples (') quanto duplas ("). Isso é importante sempre que você insere um valor dentro de um atributo HTML, pois uma aspa não escapada pode fechar o atributo prematuramente e injetar novos atributos.

Saída:

I'm a paragraph

A aspa simples foi convertida para '. Os valores de flags mais comuns são:

• ENT_QUOTES — converte tanto aspas duplas quanto simples (recomendado).
• ENT_COMPAT — converte aspas duplas, deixa as simples intactas.
• ENT_NOQUOTES — deixa ambos os tipos de aspas sem conversão.
• ENT_SUBSTITUTE — substitui sequências de unidades de código inválidas por � em vez de retornar uma string vazia.

O parâmetro $encoding

O terceiro parâmetro, $encoding, indica a codificação de caracteres da string de entrada. O padrão é o valor da configuração INI default_charset (UTF-8 em instalações modernas). Defini-lo explicitamente evita surpresas se a entrada estiver em uma codificação diferente.

Saída:

Tom & Jerry

Aqui o e comercial é codificado como & enquanto PHP interpreta a entrada como UTF-8. Se a codificação não corresponder aos bytes reais de $string, a função pode retornar uma string vazia (ou um caractere de substituição quando ENT_SUBSTITUTE está definido).

O parâmetro $double_encode

O quarto parâmetro, $double_encode, controla se as entidades existentes serão codificadas novamente. Por padrão é true, então uma string que já contém < se torna <. Defina como false para deixar as entidades já codificadas intactas — útil quando a entrada já foi parcialmente escapada.

Saída:

Hello <strong>World</strong>!

As entidades < e > existentes são deixadas sem alteração porque $double_encode é false. Com o valor padrão true, a mesma entrada teria produzido Hello <strong>....

Prevenindo XSS na prática

O uso mais importante de htmlspecialchars() é escapar qualquer dado que você não controla completamente — entradas de formulário, valores de query string, registros de banco de dados que vieram de usuários — antes de exibi-los em uma página:

<?php
$comment = $_GET['comment'] ?? '';   // e.g. "<script>alert('xss')</script>"
echo "<p>" . htmlspecialchars($comment, ENT_QUOTES, "UTF-8") . "</p>";
?>

A tag <script> é neutralizada em <script>...</script>, fazendo o navegador exibir o texto em vez de executá-lo. Aplique o escape no momento da saída, não ao armazenar os dados, para que o valor bruto permaneça disponível para outros contextos.

Revertendo a conversão

Para transformar as entidades de volta nos seus caracteres originais, use htmlspecialchars_decode(). Passe as mesmas flags usadas na codificação para que as aspas sejam tratadas simetricamente.

Funções relacionadas

• htmlentities() — como htmlspecialchars(), mas converte todos os caracteres que possuem entidades HTML equivalentes, não apenas os cinco especiais.
• htmlspecialchars_decode() — o inverso desta função.
• strip_tags() — remove completamente as tags HTML e PHP em vez de escapá-las.
• nl2br() — insere <br> antes de quebras de linha, geralmente usado após escapar texto simples.

Resumo

Use htmlspecialchars() sempre que exibir texto não confiável em HTML. Passe ENT_QUOTES e uma codificação UTF-8 explícita para resultados previsíveis e seguros em todas as versões do PHP, escape no momento da saída e recorra a htmlentities() apenas quando precisar codificar todas as entidades, e não apenas os cinco caracteres especiais.

Prática