htmlspecialchars

(PHP 4, PHP 5, PHP 7, PHP 8)

htmlspecialchars — Converte caracteres especiais para entidades HTML

Descrição

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

Certos caracteres têm significado especial em HTML, e devem ser representados por entidades HTML se for necessário preservar seus significados. Esta função retorna uma string com estas conversões realizadas. Se for necessário traduzir todas as substrings de entrada que têm entidades nomeadas associadas, use htmlentities() no lugar desta função.

Se a string de entrada passada para esta função e o documento final compartilham o mesmo conjunto de caracteres, esta função é suficiente para preparar a entrada para inclusão na maioria dos contextos de um documento HTML. Se, por outro lado, a entrada puder representar caracteres que não são codificados no conjunto de caracteres do documento final, e for necessário reter esses caracteres (como entidades numéricas ou nomeadas), tanto esta funçã quanto htmlentities() (que apenas codifica substrings que têm entidades nomeadas equivalentes) podem ser insuficientes. Pode ser necessário usar mb_encode_numericentity() no lugar desta função.

Traduções realizadas
Caractere Substituição
& (e comercial) &
" (asplas duplas) ", a menos que ENT_NOQUOTES esteja definida
' (aspas simples) ' (para ENT_HTML401) ou ' (para ENT_XML1, ENT_XHTML ou ENT_HTML5), mas apenas quando ENT_QUOTES estiver definida
< (menor que) &lt;
> (maior que) &gt;

Parâmetros

string

A string a ser convertida.

flags

Uma máscara de bits de uma ou mais das opções a seguir, que especificam como lidar com aspas, com sequências de unidade de código inválidas e o tipo de documento usado. O padrão é ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.

Constantes disponíveis para flags
Nome da Constante Descrição
ENT_COMPAT Converte aspas duplas e não converte aspas simples.
ENT_QUOTES Converte tanto aspas duplas quanto simples.
ENT_NOQUOTES Não converte aspas duplas ou simples.
ENT_IGNORE Descarta silenciosamente as sequências de unidade de código inválidas ao invés de retornar uma string vazia. É desencorajado o uso desta já que » podem haver implicações em segurança.
ENT_SUBSTITUTE Substitui sequências de unidade de código inválidas com um Caractere de Substituição Unicode U+FFFD (UTF-8) ou &#xFFFD; ao invés de retornar uma string vazia.
ENT_DISALLOWED Substitui pontos de código inválidos para o tipo de documento fornecido com um Caractere de Substituição Unicode U+FFFD (UTF-8) ou &#xFFFD; ao invés de deixá-lo inalterado. Isto pode ser útil, por exemplo, para garantir a boa formatação de documentos XML com conteúdo externo incluído.
ENT_HTML401 Lida com o código como HTML 4.01.
ENT_XML1 Lida com o código como XML 1.
ENT_XHTML Lida com o código como XHTML.
ENT_HTML5 Lida com o código como HTML 5.
encoding

Um argumento opcional que define a codificação usada na conversão de caracteres.

Se omitido, encoding assume como padrão o valor da opção de configuração default_charset .

Embora este argumento seja tecnicamente opcional, especificar o valor correto para o código é altamente recomendável se a opção de configuração default_charset puder ser definida incorretamente para a entrada fornecida.

Para os propósitos desta função, as codificações ISO-8859-1, ISO-8859-15, UTF-8, cp866, cp1251, cp1252 e KOI8-R são efetivamente equivalentes, desde que o parâmetro string em si seja válido para a codificação, já que os caracteres afetados por htmlspecialchars() ocupam as mesmas posições em todas estas codificações.

Os seguintes conjuntos de caracteres são suportados:

Conjuntos de caracteres suportados
Conjunto de caracteres Apelidos Descrição
ISO-8859-1 ISO8859-1 Western European, Latin-1.
ISO-8859-5 ISO8859-5 Conjunto de caracteres cirílicos pouco usado (Latim/Cirílico).
ISO-8859-15 ISO8859-15 Western European, Latin-9. Adiciona o símbolo do Euro, letras Francesas e Filandesas faltando no Latin-1 (ISO-8859-1).
UTF-8   Código de multi-byte 8-bit Unicode compatível com ASCII.
cp866 ibm866, 866 Conjunto de caracteres do DOS específico para o Russo.
cp1251 Windows-1251, win-1251, 1251 Conjunto de caracteres do Windows específico para o Russo.
cp1252 Windows-1252, 1252 Conjunto de caracteres do Windows específico para a Europa Ocidental.
KOI8-R koi8-ru, koi8r Russo.
BIG5 950 Chinês Tradicional, usado principalmente em Taiwan.
GB2312 936 Chins Simplificado, conjunto de caracteres padrão nacional.
BIG5-HKSCS   Big5 com extenções de Hong Kong, Chinês Tradicional.
Shift_JIS SJIS, SJIS-win, cp932, 932 Japonês
EUC-JP EUCJP, eucJP-win Japonês
MacRoman   Conjunto de caracteres que era usado pelo Mac OS.
''   Uma string vazia ativa a detecção a partir de codificação de script (multibyte Zend), conjunto padrão de caracteres e localidade atual (consulte nl_langinfo() e setlocale()), nesta ordem. Não recomendado.

Note: Nenhum outro conjunto de caracteres é reconhecido. A codificação padrão será usada no lugar e um alerta será emitido.

double_encode

Quando double_encode estiver desligada, o PHP não codificará entidades HTML existentes, o padrão é converter tudo.

Valor Retornado

A string convertida.

Se a string de entrada contiver uma sequência de unidade de código inválida na codificação informada em encoding, uma string vazia será retornada, a menos que ENT_IGNORE ou ENT_SUBSTITUTE esteja definida.

Registro de Alterações

Versão Descrição
8.1.0 O padrão para flags mudou de ENT_COMPAT para ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.

Exemplos

Example #1 Exemplo de htmlspecialchars()

<?php
$new = htmlspecialchars("<a href='test'>Test</a>", ENT_QUOTES);
echo $new; // &lt;a href=&#039;test&#039;&gt;Test&lt;/a&gt;
?>

Notas

Note:

Observe que esta função não traduz nada além do que está listado acima. Para tradução completa de entidade, consulte htmlentities().

Note:

Em caso de um valor ambíguo no parâmetro flags, as seguintes regras se aplicam:

Veja Também