Notifications avancées

Description

Ce plugin est avant tout un outil de développement, qui permet de déclarer des notifications possibles et fournit des moyens pour gérer des abonnements et des désistements pour celles-ci.

On part du principe qu’une notification c’est :

• un contenu, possiblement en plusieurs format (texte brut, HTML, court)
• des destinataires par défaut, choisis par la notification elle-même
• des destinataires explicites, qui se sont abonnés
• des rabats-joie qui veulent bloquer une notification
• optionnellement des préférences qui conditionnent l’envoi ou pas pour un destinataire
• des modes d’envoi (email, jabber, sms, pigeon...)

Tous ces éléments sont alors programmables lors du développement de la notification, de manière assez fines, et toujours optionnelle. On peut donc déclarer une notification avec juste un squelette SPIP, ou bien imaginer des choses plus complexes.

Appeler une notification

Tout d’abord, pour utiliser une notification, il faut qu’elle soit appelée quelque part. C’est la fonction classique de SPIP :

// Chargement de la fonction
$notifications = charger_fonction('notifications', 'inc/');

// Appel générique
$notifications('truc', $id, $options);

// Exemple
$notifications('patate_instituer', $id_patate, array('avant' => $statut_avant, 'apres' => $statut_apres));

Contenu de la notification

Une notification sans contenu, c’est comme une mouche sans ailes. Plusieurs moyens sont proposés pour indiquer ce qui sera envoyé.

Uniquement en créant des squelettes

• notifications/truc.html correspond au texte brut de la notification, c’est le minimum à fournir pour l’envoi par email
• notifications/truc_html.html correspond à la version HTML
• notifications/truc_court.html correspond au format court, de type SMS ou Microblog (limité en caractères, donc)

Ces trois squelettes reçoivent diverses informations utiles en contexte :

• quoi : le nom de la notification
• id : l’identifiant passé en paramètre
• options : l’éventuel tableau d’options
• mode : le mode d’envoi pour lequel on est en train de générer le contenu
• destinataire : un id_auteur (souvent) ou bien une information de contact (adresse email par exemple)
• contact : toujours l’information de contact en rapport avec le mode d’envoi utilisé
• objet, id_objet, id_truc : les informations sur l’objet concerné par la notification en utilisant le même principe que pour les modèles : le premier mot du nom de la notification est le type de l’objet (article_instituer, patate_supprimer, etc).

En passant par PHP

Vous pouvez aussi créer une fonction notifications_truc_contenu_dist($id, $options, $destinataire, $mode) dans le fichier notifications/truc.php. Cela permet parfois plus de possibilités ou de lisibilité.

Cette fonction prend en paramètre l’identifiant et le tableau d’options qui ont pu être passé dans la notification, mais aussi le destinataire à qui est en train d’être envoyé le message (un id_auteur ou une info de contact, comme précédemment), ainsi que le mode d’envoi (« email » par exemple).

La fonction peut soit renvoyer directement un texte, ce qui correspondra au texte brut de la notification, soit renvoyer un tableau avec trois clés optionnelles :

• texte : le texte brut du message
• html : la version HTML
• court : la version courte

Pour chaque possibilité, si la clé n’existe pas dans le tableau, alors le plugin cherchera le squelette correspondant dans la première méthode, sinon rien.

Destinataires

Désormais, votre notification existe. Mais elle ne sera jamais envoyée à personne si elle n’a pas de destinataires ! Le plugin permet trois sources d’où peuvent provenir les malheureux spammés. :) :

1. Une liste définie lors du développement de la notification.
2. Des gens abonnés explicitement, stockés dans une table de la base.
3. Ces deux sources s’additionnent, et une fois la liste constituée, elle passe dans le pipeline notifications_destinataires, et peut donc être étendue.

Destinataires par défaut

Vous pouvez définir les destinataires d’une notification en créant la fonction notifications_truc_destinataires_dist($id, $options) dans le fichier notifications/truc.php.

La liste est un tableau donc chaque élément est un destinataire. Ce dernier peut être décrit de trois manières différentes suivant vos besoins ou infos à votre disposition :

• un id_auteur : c’est le cas le plus courant et le plus générique, car il permet ensuite d’envoyer par plusieurs modes d’envoi
• une adresse de courriel : dans ce cas seul le mode d’envoi « email » pourra être utilisé, c’est un cas possible pour des forums publics par exemple où les gens ne sont pas inscrits
• un tableau explicite des modes d’envoi : enfin on peut décrire explicitement comment sera envoyé le message à un destinataire, avec un tableau dont chaque clé est le nom d’un mode d’envoi, et la valeur de la clé est l’information de contact pour ce mode d’envoi

Exemple :

function notifications_truc_destinataires_dist($id, $options){
	return array(
		16, 38,12,  // des id_auteur
		'paul@personne.fr', 'livarot@fromage.com', // des emails
		array( // un tableau explicite pour UN destinataire
			'email'=>'truc@bidule.net',
			'sms'=>'0606060606',
			'jabber'=>'truc@jabber.fr'
		),
	);
}

Destinataires abonnés

La deuxième méthode consiste à fournir à vos utilisateurs des moyens pour s’abonner explicitement à une notification. Le plugin contient donc une table dédiée à cela, ainsi que des actions.

La table des abonnements contient :

• id_auteur : l’utilisateur concerné par cet abonnement, peut valoir 0 si on utilise plutôt l’information de contact
• contact : une information de contact si ce n’est pas pour un utilisateur inscrit (par exemple une adresse email)
• quoi : le nom de la notification
• id : l’identifiant éventuel pour cette notification
• preferences : un éventuel tableau (sérialisé pour le stockage) contenant les préférences de l’abonné, si la notification en utilise
• modes : un tableau (sérialisé aussi) contenant la liste des modes d’envoi à utiliser pour cet abonné ; si cette liste est vide, cela signifie que l’utilisateur ne veut PAS recevoir cette notification (blacklist)
• actif : 1 pour activer l’abonnement, 0 pour le désactiver

Action « abonner_notification »

Cette action permet d’abonner peut être utilisée soit telle quelle pour un abonnement très simple, soit dans le traitement d’un formulaire.

Par défaut, elle abonne l’utilisateur actuellement connecté, uniquement par email, en prenant en paramètre la notification « quoi-id » :
#URL_ACTION_AUTEUR{abonner_notification, truc-32}

Mais on peut aussi l’appeler en PHP :

$abonner = charger_fonction('abonner_notification', 'action/');
$abonner('truc-32', $modes, $preferences);

On peut donc optionnellement passer deux tableaux $modes et $preferences, qui seront utilisés pour cet abonnement.

L’action sait aussi récupérer les POST contact pour l’information de contact si ce n’est pas pour un utilisateur, modes et preferences qui seront utilisés si on ne les fournit pas à la fonction.
On peut donc facilement utiliser cette fonction comme traitement d’un formulaire.

À terme le but est de savoir générer automatiquement des formulaires pour s’abonner ou pour configurer des abonnements.

Programmer des préférences

Une notification complexe peut définir une fonction qui indiquera pour chaque destinataire abonné (ceux qui sont dans la table) s’il doit recevoir ou pas le message suivant des préférences qu’il aurait.

Pour cela il faut définir une fonction notifications_truc_preferences_dist($id, $options, $preferences) dans le fichier notifications/truc.php.

En plus des informations classique de la notification, la fonction reçoit les préférences d’un destinataire. Normalement ces dernières ne sont jamais vides puisque la fonction n’est justement appelée que s’il y a des préférences.

On doit renvoyer « true » ou « false », suivant que le destinataire doit être ajouté ou pas.

Ne plus recevoir une notification

Le système d’abonnements explicites permet de s’assurer que vos utilisateurs veulent vraiment recevoir une notification. Mais comme nous l’avons vu, certaines notifications définissent elles-mêmes leur liste de destinataires, et ces derniers n’ont donc pas leur mot à dire.

Avec la même table, on permet donc la désinscription explicite à une notification. Vous pouvez donc proposer à vos utilisateurs de ne surtout pas recevoir telle ou telle notification.

Pour cela, il faut les abonner à une notification avec une liste de modes d’envoi vide. Cela signifiera qu’ils sont blacklistés pour cette notification.

Modes d’envoi

Les modes d’envoi sont un ensemble de fonctions PHP placées dans notifications/modes/bidule.php.

Pour implémenter un nouveau mode d’envoi, il faut deux fonctions :

• notifications_modes_bidule_envoyer_dist($contact, $contenu) qui va envoyer le contenu au contact par le mode bidule
  • $contact contient une information de contact déjà vérifiée et cohérente avec le mode
  • $contenu est un tableau pouvant contenir « texte », « html » et « court », les trois formats de message
• notifications_modes_bidule_contact_dist($destinataire) qui doit renvoyer une information de contact cohérente avec le mode en question (une adresse email pour le mode « email », un numéro pour le mode « sms », etc) par rapport au destinataire passé en paramètre
  • $destinataire peut être une information de contact à vérifier et si c’est bon la garder, sinon renvoyer « null »
  • ou bien cela peut être un id_auteur, et dans ce cas la fonction doit essayer de trouver une information de contact valable pour ce mode en rapport avec cet id_auteur, sinon renvoyer « null »

Il faut ensuite créer un fichier bidule.yaml au même endroit, afin de déclarer ce mode d’envoi. Le fichier doit contenir :

titre: 'Nom du mode'
description: 'Une description un peu plus longue'

# On peut utiliser des chaînes de langue simple
titre: '<:truc:bidule_titre:>'

Encore à faire

Le noyau des fonctionnalités est normalement assez complet. Maintenant ce qu’il manque, ce sont les interfaces et formulaires prêt-à-l’emploi pour gérer les notifications.

Il faudrait donc faire :

• un formulaire de configuration pour les admins qui liste automatiquement toutes les notifications déclarées afin de les activer ou pas pour l’ensemble du site
• un formulaire pour gérer les abonnements d’un auteur (un début simple existe) listant ses abonnements actuels et permettant de les modifier
• un formulaire permettant de créer ou modifier un abonnement et sachant automatiquement générer les champs pour les préférences qui auraient été décrites dans le fichier de déclaration de la notification (en YAML)