====== Création de filtres antispam ======

===== Généralités =====

La création de filtres supplémentaires pour le plugin antispam n'est pas compliquée, elle consiste à faire un plugin tout simple contenant une classe de filtrage. Cette classe va prendre en charge la reconnaissance du message comme un spam, l'entraînement éventuel du filtre, l'affichage d'une possible interface de configuration et l'affichage de messages d'information concernant le spam.

Nous allons ici voir comment réaliser un filtre tout simple.

===== Définition du plugin =====

Comme d'habitude, tout commence par un répertoire dans vos plugins, contenant un fichier **_define.php** :

<code php>
<?php
if (!defined('DC_RC_PATH')) { return; }

$this->registerModule(
	/* Name */			"FooFilter",
	/* Description*/		"Foo Spam Filter",
	/* Author */			"Peter McAlloway",
	/* Version */			'1.0',
	/* Permissions */		'usage,contentadmin',
	/* Priority */			200
);
?>
</code>

<note>Spécifiez toujours une priorité supérieure à 10 sinon votre filtre ne va pas fonctionner.</note>

Maintenant, nous devons déclarer notre nouveau filtre à $core. Nous allons faire ceci dans un fichier **_prepend.php** :

<code php>
<?php
if (!defined('DC_RC_PATH')) { return; }

global $__autoload, $core;
$__autoload['dcFilterFoo'] = dirname(__FILE__).'/class.dc.filter.foo.php';
$core->spamfilters[] = 'dcFilterFoo';
?>
</code>

Ce fichier indique au système de chargement automatique de classes où trouver la classe de filtrage puis ajoute le filtre (le nom de la classe) aux autres filtres dans $core->spamfilters.

===== Création du filtre =====

Nous avons déclaré une classe de filtrage mais celle-ci n'existe pas, c'est un peu dommage. Nous allons donc de ce pas créer un fichier **class.dc.filter.foo.php** dans notre plugin :

==== La classe de filtrage ====

<code php>
<?php
class dcFilterFoo extends dcSpamFilter
{
	public $name = 'Foo Filter';
	public $has_gui = false;
	public $active = false;
	
	protected function setInfo()
	{
		$this->description = __('My new foo spam filter');
	}
}
?>
</code>

<note important>
Votre classe de filtre doit impérativement être enfant de **dcSpamFilter** sinon elle ne sera même pas chargée.
</note>

Nous venons de réaliser un filtre dont le nom est "Foo Filter", avec une description qui sera affichée dans la liste des filtres. Le paramètre **$has_gui = false** indique que notre filtre n'a pas d'écran de configuration. Le paramètre **$active = false** indique que le filtre est inactif par defaut.

<note tip>
La classe ainsi créée dispose d'une propriété $this->core permettant d'accéder à tous les objets utiles de Dotclear (base de données, blog en cours, permissions...).
</note>

==== La méthode isSpam ====

Notre filtre est pour le moment parfaitement inutile puisqu'il ne contient pas de méthode pour reconnaître un spam. Cette méthode s'appelle **isSpam**, nous allons l'ajouter (dans le corps de la classe donc) :

<code php>
<?php
...
public function isSpam($type,$author,$email,$site,$ip,
$content,$post_id,&$status)
{
	$status = 'Filtered';
	return true;
}
...
</code>

Ici, notre méthode va déclarer que tous les commentaires sont du spam et assigner le status "Filtered" à celui-ci.

Cette méthode prend les paramètres suivants :

  * $type : le type de commentaire (//comment// ou //trackback//)
  * $author : le nom de l'auteur
  * $email : l'adresse email de l'auteur
  * $site : l'URL du site de l'auteur
  * $ip : l'adresse IP de l'auteur
  * $content : le contenu du commentaire
  * $post_id : l'ID du billet sur lequel le commentaire a été posté

La dernière variable $status doit bien être déclarée en référence (**&**$status) puisqu'elle permet de transmettre le statut du commentaire si celui-ci est marqué comme spam.

Cette méthode doit renvoyer **true** si le message est un spam et **null** si on ne sait pas.

<note warning>
Si la méthode renvoie **false** le message sera immédiatement reconnu comme **non spam** quel que soit les résultats des autres filtres. Ça peut-être utile dans certains cas mais faites attention à ne pas vous tromper.
</note>

==== La méthode getStatusMessage ====

Cette méthode doit renvoyer une chaîne contenant une information sur le pourquoi du filtrage. Elle sera affichée après chaque commentaire dans les listes ou dans la page d'édition de ceux-ci.

Pour notre filtre, voici ce que nous pouvons indiquer (toujours en ajoutant cette méthode dans le corps de la classe) :

<code php>
<?php
...
public function getStatusMessage($status,$comment_id)
{
	return sprintf(__('Filtered by %s.'),$this->guiLink());
}
...
?>
</code>

Chaque commentaire filtré par votre plugin indiquera "Filtré par Foo Filter". Vous n'êtes pas obligé de créer cette méthode. Dans ce cas, vous aurez une indication par défaut : "Filtré par Foo Filter (raison)".

==== La méthode trainFilter ====

Si votre filtre nécessite qu'on lui apprenne à reconnaître un spam ou un non-spam, cette méthode peut être nécessaire. Elle sera appelée dans les cas suivants :

  * On passe un commentaire qui n'est pas un spam en spam
  * On publie un commentaire qui est un spam

Dans ces deux cas, les méthodes **trainFilter** de chaque filtre seront appelées.

La méthode prend les paramètres suivants :

  * $status : Statut du commentaire (//spam// si on déclare un spam, //ham// si on déclare un non spam)
  * $filter : Filtre qui a été appliqué sur le commentaire si celui-ci était un spam
  * $type : Type de commentaire (//comment// ou //trackback//)
  * $author : Nom de l'auteur
  * $email : Adresse email de l'auteur
  * $site : URL du site de l'auteur
  * $ip : Adresse IP de l'auteur
  * $content : Contenu du commentaire
  * $rs : Objet de type record contenant d'autres informations sur le commentaire

Votre méthode se déclare donc comme ceci :

<code php>
<?php
...
public function trainFilter($status,$filter,$type,$author,
$email,$site,$ip,$content,$rs)
{
	// Choses à faire pour entraîner le filtre
}
...
?>
</code>

==== La méthode gui ====

La methode gui($url) permet de créer l'interface de configuration de votre filtre. Pour que celle-ci soit active, vous devez spécifier **public $has_gui = true;** au début de votre classe.

Cette méthode prend un seul paramètre : l'URL de configuration du filtre.

Par exemple, une interface toute simple de votre filtre :

<code php>
<?php
...
public function gui($url)
{
	return '<p>My filter GUI</p>';
}
...
?>
</code>

<note>
Le paramètre $url contient des caractères spéciaux, pensez à l'afficher dans la page avec html::escapeHTML($url). Vous n'avez par contre pas besoin de faire ça, si vous faites une redirection vers $url.
</note>

===== Conclusion =====

Vous avez pu voir que faire un filtre antispam n'est pas bien compliqué. Afin d'approfondir ce court tutoriel, vous êtes encouragés à lire le code des filtres intégrés dans le plugin antispam (dans le répertoire "filters" de celui-ci).

===== Modèle de code pour une classe de filtrage =====

Voici un modèle de classe pour réaliser un filtre. **Pensez à changer le nom de la classe**.

<code php>
<?php
class dcFilterFirst extends dcSpamFilter
{
	public $name = 'Filter Name'; // The name of your filter
	public $has_gui = true;       // Has your filter a GUI?
	
	// Set here the localized description of your filter
	protected function setInfo()
	{
		$this->description = __('My first spam filter');
	}
	
	/*
	You may need this method or let parent method do its job.
	public function getStatusMessage($status,$comment_id)
	{
		return sprintf(__('Filtered by %s.'),$this->guiLink());
	}
	*/
	
	public function isSpam($type,$author,$email,
		$site,$ip,$content,$post_id,&$status)
	{
		/*
		return true and set $status if message is a spam
		return null if you don't know (not false)
		*/
	}
	
	/*
	Only if you need to train your filter
	public function trainFilter($status,$filter,$type,
		$author,$email,$site,$ip,$content,$rs)
	{
	}
	*/
	
	// A totaly useless GUI
	public function gui($url)
	{
		return '<p>'.__('My filter GUI').'</p>';
	}
}
?>
</code>