Helper HTMLCleaner

1Apresentação

A principal função deste helper é limpar um fluxo HTML proveniente de um editor WYSIWYG, garantindo que ele não contenha nenhum código proibido. Nesse sentido, ele é uma camada sobre a biblioteca HTMLPurifier.

Ele também oferece a possibilidade de converter texto puro em um fluxo HTML.

2Instalação

Para funcionar corretamente, o objeto HTMLCleaner precisa da biblioteca HTMLPurifier. Existem três soluções para instalá-la.

2.1Instalação via sistema

O método recomendado é usar os pacotes do seu sistema operacional. Por exemplo, no Ubuntu, o HTMLPurifier pode ser instalado facilmente com este comando: 

$ sudo apt install php-htmlpurifier

2.2Instalação via Composer

Também é possível usar o gerenciador de dependências Composer (veja a documentação dedicada). Para isso, execute o seguinte comando a partir da raiz do projeto: 

$ composer require ezyang/htmlpurifier

2.3Instalação manual

Você também tem a possibilidade de baixar os arquivos manualmente e copiá-los no diretório lib/ do seu projeto.

Atenção: se você colocar os arquivos em um subdiretório (chamado "htmlpurifier", por exemplo), será necessário declarar esse subdiretório na lista de caminhos de inclusão (veja a documentação de configuração). Neste caso, adicione estas linhas no seu arquivo etc/temma.php: 

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

3clean()

Função estática que recebe um fluxo HTML e retorna o mesmo fluxo após sua limpeza. Tags HTML não autorizadas são removidas. Atributos de tags não autorizados também são removidos. Múltiplas quebras de linha são transformadas em parágrafos.

Assinatura do método:

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

Parâmetros:

  • $html: Fluxo HTML a ser limpo.
  • $targetBlank: Indica se um atributo target="_blank" deve ser adicionado aos links.
    • true para adicionar o atributo a todos os links.
    • false para nunca adicionar o atributo.
    • null para adicionar o atributo apenas aos links externos (que começam com http:// ou https://).
  • $nofollow: Indica se um atributo rel="nofollow" deve ser adicionado aos links.
    • true para adicionar o atributo a todos os links.
    • false para nunca adicionar o atributo.
    • null para adicionar o atributo apenas aos links externos (que começam com http:// ou https://).
  • $removeNbsp: Indica se os espaços não separáveis devem ser removidos.

Valor retornado: fluxo HTML limpo.

Exemplo:

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

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

4text2html()

Função estática que recebe texto puro e retorna um fluxo HTML. Quebras de linha e parágrafos (blocos de texto separados por uma linha em branco) são tratados, assim como os links.

Assinatura do método:

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

Parâmetros:

  • $text: Texto a ser processado.
  • $urlProcess: true para processar as URLs. Links para sites externos (que começam com http:// ou https://) abrem em uma nova aba (target="_blank").
  • $nofollow: true para definir as URLs como nofollow.

Valor retornado: fluxo HTML gerado.

Exemplo:

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

$text = "First paragraph,
on two lines.

Site: https://www.temma.net";
$html = TµHTMLCleaner::text2html($text);
/*
<p>First paragraph,<br />
on two lines.</p>
<p>Site: <a target="_blank" rel="nofollow"
href="https://www.temma.net">https://www.temma.net</a></p>
*/