htmlspecialchars

(PHP 4, PHP 5)

htmlspecialchars — Convierte caracteres especiales en entidades HTML

Descripción

string htmlspecialchars ( string $string [, int $flags = ENT_COMPAT | ENT_HTML401 [, string $encoding = ini_get("default_charset") [, bool $double_encode = true ]]] )

Ciertos caracteres tienen un significado especial en HTML y deben ser representados por entidades HTML si se desea preservar su significado. Esta función devuelve un string con estas conversiones realizadas. Si se requiere que todas las subcadenas de entrada tengan asociadas entidades con nombre para que sean traducidas, use htmlentities() en su lugar.

Si el string de entrada pasado a esta función y el documento final comparten el mismo conjunto de carcteres, esta función es suficiente para preparar entradas para su inclusión en la mayoría de los contextos de un documento HTML. Sin embargo, si la entrada puede representar caracteres que no están codificados en el conjunto de caracteres del documento final, y es necesario conservar dichos caracteres (tales como números o entidades con nombre), esta función y htmlentities() (la cual solamente codifica subcadenas que tienen equivalentes de entidades con nombre) podrían ser insuficientes. Se podria usar mb_encode_numericentity() en su lugar.

Las traducciones realizadas son:

  • '&' (et) se convierte en '&'
  • '"' (comillas dobles) se convierte en '"' cuando ENT_NOQUOTES no está establecido.
  • "'" (comilla simple) se convierte en ''' (o ') sólo cuando ENT_QUOTES está establecido.
  • '<' (menor que) se convierte en '&lt;'
  • '>' (mayor que) se convierte en '&gt;'

Parámetros

string

El string a convertir.

flags

Una máscara de bits de una o más de los siguientes indicadores, los cuales especifican cómo manejar las comillas, las secuencias de unidad de código inválidas y el tipo de documento utilizado. El valor predeterminado es ENT_COMPAT | ENT_HTML401.
Constantes disponibles para flags
Nombre de la constante Descripción
ENT_COMPAT Convertirá las comillas dobles y sólo dejará las comillas simples.
ENT_QUOTES Convertirá tanto las comillas dobles como las simples.
ENT_NOQUOTES Dejará tanto las comillas dobles como las simples sin convertir.
ENT_IGNORE Descartar silenciosamente unidades de secuencia de código no válidas en lugar de devolver un string vacío. No se recomienda el uso de este indicador, ya que » puede tener implicaciones de seguridad.
ENT_SUBSTITUTE Reemplazar las secuencias de unidad de código inválidas con un Carácter de Reemplazo Unicode U+FFFD (UTF-8) o &#FFFD; (no UTF-8) en lugar de devolver un string vacío.
ENT_DISALLOWED Reemplazar los puntos de código no válidos para el tipo de documento dado con un Carácter de Reemplazo Unicode U+FFFD (UTF-8) o &#FFFD; (no UTF-8) en lugar de dejarlos tal cual. Esto puede ser útil, por ejemplo, para asegurar que los documentos XML estén bien formados con contenido externo incrustado.
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 el propósito de ésta función, los juegos de caracteres ISO-8859-1, ISO-8859-15, UTF-8, cp866, cp1251, cp1252 y KOI8-R son realmente equivalentes, siempre y cuando el string sea válido para la codificación, ya que los caracteres afectados por htmlspecialchars() ocupan las mismas posiciones en todas estas codificaciones.

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 double_encode se desactiva, PHP no codificará las entidades HTML existentes. El valor predeterminado es convertirlo todo.

Valores devueltos

El string convertido.

Si el string de entrada contiene una secuencia de unidad de código no válida en encoding, devolverá un string vacío, a menos que cualquiera de los indicadores ENT_IGNORE o ENT_SUBSTITUTE estén establecidos.

Historial de cambios

Versión Descripción
5.6.0 El valor predeterminado para el parámetro encoding se cambió para que fuera el valor de la opción de configuración default_charset.
5.4.0 El valor predeterminado del parámetro encoding se cambió a UTF-8.
5.4.0 Se añadieron las constantes ENT_SUBSTITUTE, ENT_DISALLOWED, ENT_HTML401, ENT_XML1, ENT_XHTML y ENT_HTML5.
5.3.0 Se añadió la constante ENT_IGNORE.
5.2.3 Se añadió el parámetro double_encode.

Ejemplos

Ejemplo #1 Ejemplo de htmlspecialchars()

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

Notas

Nota:

Se ha de tener en cuenta que esta función no traduce nada más de lo que aparece en la lista de arriba. Para la traducción completa de entidades, véase htmlentities().

Ver también