(PHP 4, PHP 5, PHP 7, PHP 8)
htmlspecialchars — Converte caracteres especiais para entidades HTML
$string
,$flags
= ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401,$encoding
= null
,$double_encode
= true
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.
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) |
< |
> (maior que) |
> |
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
.
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 � 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 � 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:
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. |
Nota: 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.
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.
Versão | Descrição |
---|---|
8.1.0 |
O padrão para flags mudou de ENT_COMPAT para ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401 .
|
Exemplo #1 Exemplo de htmlspecialchars()
<?php
$new = htmlspecialchars("<a href='test'>Test</a>", ENT_QUOTES);
echo $new; // <a href='test'>Test</a>
?>
Nota:
Observe que esta função não traduz nada além do que está listado acima. Para tradução completa de entidade, consulte htmlentities().
Nota:
Em caso de um valor ambíguo no parâmetro
flags
, as seguintes regras se aplicam:
- Quando nenhuma das constantes
ENT_COMPAT
,ENT_QUOTES
ouENT_NOQUOTES
estiver presente, o padrão éENT_NOQUOTES
.- Quando mais que uma das constantes
ENT_COMPAT
,ENT_QUOTES
ouENT_NOQUOTES
estiverem presentes,ENT_QUOTES
tem a maior precedência, seguida porENT_COMPAT
.- Quando nenhuma das constantes
ENT_HTML401
,ENT_HTML5
,ENT_XHTML
ouENT_XML1
estiver presente, o padrão éENT_HTML401
.- Quando mais que uma das constantes
ENT_HTML401
,ENT_HTML5
,ENT_XHTML
ouENT_XML1
estiverem presentes,ENT_HTML5
tem a maior precedência, seguida porENT_XHTML
,ENT_XML1
eENT_HTML401
.- Quando mais que uma das constantes
ENT_DISALLOWED
,ENT_IGNORE
ouENT_SUBSTITUTE
estiverem presentes,ENT_IGNORE
tem a maior precedência, seguida porENT_SUBSTITUTE
.