Helper HTMLCleaner

1Presentación

La función principal de este helper es limpiar un flujo HTML procedente de un editor WYSIWYG, para garantizar que no contenga código prohibido. En ese sentido, es una capa sobre la biblioteca HTMLPurifier.

También ofrece la posibilidad de convertir texto plano en un flujo HTML.

2Instalación

Para funcionar correctamente, el objeto HTMLCleaner necesita la biblioteca HTMLPurifier. Hay tres formas de instalarla.

2.1Instalación mediante el sistema

El método recomendado es usar los paquetes de tu sistema operativo. Por ejemplo, en Ubuntu, HTMLPurifier se puede instalar fácilmente con este comando: 

$ sudo apt install php-htmlpurifier

2.2Instalación mediante Composer

También es posible usar el gestor de dependencias Composer (consulta la documentación correspondiente). Para ello, ejecuta el siguiente comando desde la raíz del proyecto: 

$ composer require ezyang/htmlpurifier

2.3Instalación manual

También tienes la posibilidad de descargar los archivos manualmente, y copiarlos en el directorio lib/ de tu proyecto.

Atención: si colocas los archivos en un subdirectorio (llamado "htmlpurifier", por ejemplo), tendrás que declarar ese subdirectorio en la lista de rutas de inclusión (consulta la documentación de configuración). En ese caso, añade estas líneas en tu archivo etc/temma.php: 

[
    'includePaths' => [
        '/path/to/project/lib/htmlpurifier'
    ]
]

3clean()

Función estática que recibe un flujo HTML y devuelve el mismo flujo una vez limpiado. Se eliminan las etiquetas HTML no autorizadas. También se eliminan los atributos de etiqueta no autorizados. Los retornos de carro múltiples se transforman en párrafos.

Firma del método:

\Temma\Utils\HTMLCleaner::clean(string $html, ?bool $targetBlank=null, ?bool $nofollow=null, bool $removeNbsp=true) : string

Parámetros:

  • $html: Flujo HTML que se debe limpiar.
  • $targetBlank: Indica si se debe añadir un atributo target="_blank" a los enlaces.
    • true para añadir el atributo a todos los enlaces.
    • false para no añadirlo nunca.
    • null para añadir el atributo a los enlaces externos (que empiecen por http:// o https://).
  • $nofollow: Indica si se debe añadir un atributo rel="nofollow" a los enlaces.
    • true para añadir el atributo a todos los enlaces.
    • false para no añadirlo nunca.
    • null para añadir el atributo a los enlaces externos (que empiecen por http:// o https://).
  • $removeNbsp: Indica si se deben eliminar los espacios de no separación.

Valor devuelto: flujo HTML limpiado.

Ejemplo:

use \Temma\Utils\HTMLCleaner as TµHTMLCleaner;

$input = <<< EOT
<h1>Título
<p onclick="alert('XSS');">Párrafo<br>
<br>
<script>alert('XSS');</script>
EOT;
$output = TµHTMLCleaner::clean($input);
/*
<h1>Título</h1>
<p>Párrafo</p>
*/

4text2html()

Función estática que recibe texto plano y devuelve un flujo HTML. Se gestionan los saltos de línea y los párrafos (bloques de texto separados por una línea vacía), así como los enlaces.

Firma del método:

\Temma\Utils\HTMLCleaner::text2html(string $text, bool $urlProcess=true, bool $nofollow=true) : string

Parámetros:

  • $text: Texto que se debe procesar.
  • $urlProcess: true para procesar las URLs. Los enlaces a sitios externos (que empiecen por http:// o https://) se abren en una nueva pestaña (target="_blank").
  • $nofollow: true para poner las URLs en nofollow.

Valor devuelto: flujo HTML generado.

Ejemplo:

use \Temma\Utils\HTMLCleaner as TµHTMLCleaner;

$text = "Primer párrafo,
en dos líneas.

Sitio: https://www.temma.net";
$html = TµHTMLCleaner::text2html($text);
/*
<p>Primer párrafo,<br />
en dos líneas.</p>
<p>Sitio: <a target="_blank" rel="nofollow"
href="https://www.temma.net">https://www.temma.net</a></p>
*/