htmlspecialchars

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

htmlspecialcharsConvierte caracteres especiales en entidades HTML

Descripción

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

Algunos caracteres tienen significados especiales en HTML, y deben ser reemplazados por entidades HTML para conservar sus significados. Esta función retorna un string con estas modificaciones. Si se necesita que todas las subcadenas de entrada que están asociadas a entidades nombradas sean transformadas, se debe utilizar la función htmlentities().

Si el string de entrada pasado a esta función y el documento final comparten el mismo juego de caracteres, esta función es suficiente para preparar la entrada para una inclusión en la mayoría de los contextos de un documento HTML. Sin embargo, si la entrada puede presentar caracteres que no están codificados en el juego de caracteres del documento final, y se desea preservar estos caracteres (como numéricos o entidades nombradas), esta función y la función htmlentities() (que solo codifica las subcadenas que tienen entidades nombradas equivalentes) no son suficientes. Se debe utilizar la función mb_encode_numericentity() en su lugar.

Reemplazos realizados
Carácter Reemplazo
& (ampersand) &
" (comillas dobles) " excepto si ENT_NOQUOTES
' (comilla simple) ' (para ENT_HTML401) o ' (para ENT_XML1, ENT_XHTML o ENT_HTML5), pero solo cuando ENT_QUOTES está definido
< (menor que) &lt;
> (mayor que) &gt;

Parámetros

string

El string a convertir.

flags

Una máscara de bits de uno o más flags siguientes, que determinan la forma en que las comillas serán gestionadas, cómo se manejarán las secuencias de código inválido, así como el tipo de documento utilizado. Por omisión, es ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.

Constantes disponibles para flags
Constante Descripción
ENT_COMPAT Convierte las comillas dobles e ignora las comillas simples.
ENT_QUOTES Convierte las comillas dobles y las comillas simples.
ENT_NOQUOTES Ignora las comillas dobles y las comillas simples.
ENT_IGNORE Ignora las secuencias de caracteres inválidas en lugar de retornar un string vacío. El uso de este flag está fuertemente desaconsejado por » razones de seguridad.
ENT_SUBSTITUTE Reemplaza las secuencias de código inválido con un carácter de reemplazo Unicode U+FFFD (UTF-8) o &#xFFFD; (de lo contrario) en lugar de retornar un string vacío.
ENT_DISALLOWED Reemplaza los puntos de código inválidos del documento proporcionado con un carácter de reemplazo Unicode U+FFFD (UTF-8) o &#xFFFD; (de lo contrario) en lugar de dejarlo tal cual. Esto puede ser útil para, por ejemplo, asegurar el correcto formato de documentos XML que contienen contenido externo.
ENT_HTML401 Maneja el código como HTML 4.01.
ENT_XML1 Maneja el código como XML 1.
ENT_XHTML Maneja el código como XHTML.
ENT_HTML5 Maneja el código como HTML 5.

encoding

Un argumento opcional que define la codificación empleada al convertir caracteres.

Si se omite, el valor predeterminado de encoding varía según la versión de PHP en uso. En PHP 5.6 y posterior, la opción de configuración default_charset se emplea como valor predeterminado. PHP 5.4 y 5.5 utilizarán UTF-8 como valor predeterminado. Las versiones anteriores de PHP emplean ISO-8859-1.

Aunque este argumento es técnicamente opcional, se recomienda especificar el valor correcto para el código si se utiliza PHP 5.5 o anterior, o si la opción de configuración default_charset podría estar establecida incorrectamente para la entrada dada.

Para esta función, los encodings ISO-8859-1, ISO-8859-15, UTF-8, cp866, cp1251, cp1252, y KOI8-R son equivalentes, siempre que el parámetro string sea válido para el encoding, en el sentido de que los caracteres afectados por la función htmlspecialchars() ocupen la misma posición en todos estos encodings.

Están soportados los siguientes juegos de caracteres:

Juegos de caracteres soportados
Juego de caracteres Alias Descripción
ISO-8859-1 ISO8859-1 Europeo occidental, Latin-1.
ISO-8859-5 ISO8859-5 Juego de caracteres cirílicos poco usado (Latin/Cyrillic).
ISO-8859-15 ISO8859-15 Europeo occidental, Latin-9. Añade el signo de euro, y letras del francés y finlandés ausentes en Latin-1 (ISO-8859-1).
UTF-8   Unicode de 8 bit multibyte compatible con ASCII.
cp866 ibm866, 866 Juego de caracteres cirílico específico de DOS.
cp1251 Windows-1251, win-1251, 1251 Juego de caracteres cirílico específico de Windows.
cp1252 Windows-1252, 1252 Juego de caracteres específico de Windows para Europa occidental.
KOI8-R koi8-ru, koi8r Ruso.
BIG5 950 Chino tradicional, usado principalmente en Taiwán.
GB2312 936 Chino simplificado, juego de caracteres estándar nacional.
BIG5-HKSCS   Big5 con extensiones de Hong Kong, chino tradicional.
Shift_JIS SJIS, SJIS-win, cp932, 932 Japonés
EUC-JP EUCJP, eucJP-win Japonés
MacRoman   Juego de caracteres que fue utilizado por Mac OS.
''   Un string vacío activa la detección desde la codificación del script (Zend multibyte), default_charset y la actual configuración regional (véase nl_langinfo() y setlocale()), en este orden. No se recomienda.

Nota: No se reconoce cualquier otro juego de caracteres. Será utilizada en su lugar la codificación por defecto y se emitirá una advertencia.

double_encode

Cuando el parámetro double_encode está desactivado, PHP no codificará las entidades html existentes; por omisión, todo es convertido.

Valores devueltos

El string convertido.

Si el string de entrada string contiene una secuencia de código inválida en el parámetro encoding proporcionado, se retornará un string vacío a menos que el flag ENT_IGNORE o ENT_SUBSTITUTE esté definido.

Historial de cambios

Versión Descripción
8.1.0 flags cambió de ENT_COMPAT a ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.

Ejemplos

Ejemplo #1 Ejemplo con 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

Nota:

Tenga en cuenta que esta función no realiza ningún otro reemplazo que los que están listados anteriormente. Para realizar un reemplazo completo, consulte htmlentities().

Nota:

En el caso de un valor ambiguo para flags, se aplican las siguientes reglas:

Ver también