Présentation

La principale fonctionnalité de ce helper est de nettoyer un flux HTML provenant d'un éditeur WYSIWYG, pour s'assurer qu'il ne contient aucun code interdit.

Il offre aussi la possibilité de convertir un texte brut en flux HTML.

Installation

Pour que l'objet HTMLCleaner puisse fonctionner, il faut que la bibliothèque HTMLPurifier soit installée et accessible. Pour cela, vous avez plusieurs solutions.

Installation système

La méthode recommandée est d'utiliser les paquetages de votre système. Par exemple, sous Ubuntu, HTMLPurifier peut être facilement installé en tapant la commande suivante :

sudo apt install php-htmlpurifier

Installation avec Composer

Il est aussi possible d'utiliser le gestionnaire de dépendances Composer (voir la documentation dédiée). Pour cela, créer un fichier composer.json avec ce contenu :

{
    "require": {
        "htmlpurifier/htmlpurifier": "4.*"
    }   
}

Puis exécutez la commande composer update

Ensuite, vous devrez ajouter le chemin vers les fichiers dans la liste des chemins d'inclusion (voir la documentation de la configuration).

Dans le fichier temma.json, ajouez les lignes suivante :

{
    "includePaths": [
        "/chemin/vers/projet/vendors/htmlpurifiers/src"
    ]
}

Installation manuelle

Vous avez aussi la possibilité de télécharger les fichiers manuellement, et de les copier dans le répertoire lib/ de votre projet.

Attention, si vous les placez dans un sous-répertoire (nommé "htmlpurifier" par exemple), il faudra déclarer ce sous-répertoire dans la liste des chemins d'inclusion (voir la documentation de la configuration). Dans ce cas, il faudra ajouter les lignes suivantes dans le fichier temma.json :

{
    "includePaths": [
        "/chemin/vers/projet/lib/htmlpurifier"
    ]
}

clean()

Fonction statique qui reçoit un flux HTML et qui retourne ce même flux après l'avoir nettoyé. Les balises HTML non autorisées sont retirées. Les attributs de balises non autorisés sont retirés aussi. Les retours-chariots multiples sont transformés en paragraphes.

Signature de la méthode :

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

Paramètres :

• $html : Flux HTML à nettoyer.
• $targetBlank : Indique s'il faut mettre un attribut target="_blank" sur les liens.
  • true pour mettre l'attribut sur tous les liens.
  • false pour ne jamais ajouter l'attribut.
  • null pour ajouter l'attribut sur les liens externes (commençant par http:// ou https://).
• $nofollow : Indique s'il faut mettre un attribut rel="nofollow" sur les liens.
  • true pour mettre l'attribut sur tous les liens.
  • false pour ne jamais ajouter l'attribut.
  • null pour ajouter l'attribut sur les liens externes (commençant par http:// ou https://).
• $removeNbsp : Indique s'il faut retirer les espaces insécables.

Valeur de retour : Le flux HTML nettoyé.

Exemple :

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

$input = <<< EOT
<h1>Titre
<p onclick="alert('XSS');">Paragraphe<br>
<br>
<script>alert('XSS');</script>
EOT;
$output = TµHTMLCleaner::clean($input);
/*
<h1>Titre</h1>
<p>Paragraphe</p>
*/

text2html()

Fonction statique qui prend un texte brut et retourne un flux HTML. Les retours-chariots et les paragraphes (blocs de texte séparés par une ligne vide) sont gérés, de mêmes que les liens.

Signature de la méthode :

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

Paramètres :

• $text : Texte à traiter.
• $urlProcess : true pour traiter les URLs. Les liens vers des sites externes (commençant par http:// ou https://) s'ouvrent dans un nouvel onglet (target="_blank").
• $nofollow : true pour mettre les URL en nofollow.

Valeur de retour : Le flux HTML généré.

Exemple :

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

$text = "Premier paragraphe,
sur deux lignes.

Site : https://www.temma.net";
$html = TµHTMLCleaner::text2html($text);
/*
<p>Premier paragraphe,<br />
sur deux lignes.</p>
<p>Site : <a target="_blank" rel="nofollow"
href="https://www.temma.net">https://www.temma.net</a></p>
*/