Aller au contenu
JoeCMS Télécharger 3.1.5
Manuel · 06

Email, notifications, SMS et push

Le CMS sait envoyer : emails transactionnels avec templates et pièces jointes, notifications in-app, SMS et push via des fournisseurs. Tout n'est pas câblé au même niveau : cette page dit ce qui est prêt, ce qui est présent mais à configurer et ce qui est un échafaudage upstream.

1. Vue d'ensemble

CanalMoteurÉtat dans le dépôt
Email transactionnelprocess_mail() + PHPMailer (SMTP)en production : inscription, activation, récupération du mot de passe
Email (abstraction par services)Mailer (vendor/wolfgan/mailer/)présent ; services email_localhost (SMTP) et email_sparkpost
Notifications in-appNotifier (vendor/hcore/notifier/) + section backend /restricted/notifyprésent, avec widget et applet
Push navigateur/appdriver push_onesignal + service notification.onesignalprêt, App ID et clé REST nécessaires
SMSdrivers sms_joesmtp / sms_twilio + services sms.joesmtp / sms.twilioprêt, identifiants nécessaires
Second facteur à la connexionAuth::login + canal email ou SMS du Notifierdésactivé par défaut (AUTH_2FA), voir 08
Aperçu des emailscontents/emailpreviewer/, /srv/email-preview (règle dans modules/cms-common)présent

2. Emails transactionnels

Configuration

L'installeur écrit dans themes/site/conf/config.remote.php :

define("A_SMTP_HOST", "");  define("A_SMTP_PORT", 465);  define("A_SMTP_SECURE", "ssl");
define("A_SMTP_USER", "");  define("A_SMTP_PASSWORD", "");

Elles sont lues par vendor/wolfgan/mailer/services/email_localhost.php (et l'équivalent sparkpost). L'assistant fait un envoi de test pendant l'installation, avec un client SMTP autonome (SSL 465 / STARTTLS 587 / plain) : le courrier se vérifie avant de terminer, pas au premier utilisateur qui s'inscrit.

Envoyer

process_mail($email_struct, $to, $subject, $tpl_email_path, $fields,
             $from, $bcc, $cc, $preview, $enable_check, $invert_mail,
             $owner, $body, $attach, $prefix);

library/gallery/process/mail.php construit une structure avec thème, domaine, langue et paramètres SMTP, puis résout le template et envoie. Les templates sont dans themes/<thème>/contents/email/ — dans le dépôt, auth/activation_code.html, auth/recover_code.html et auth/account_code.html (le code du 2FA), avec les images dans email/images/. Leurs textes sont des codes du dictionnaire (svc_mail_*), donc l'email part dans la langue de composition (ci-dessous) ; jusqu'à la 3.0.3 ils étaient écrits en italien dans le fichier.

Dans quelle langue part un email

La langue du destinataire, pas celle de la requête. FF_LOCALE convient aux envois synchrones (le destinataire est celui qui vient de cliquer), mais dans un cron ou un job asynchrone — rappels, échéances, listes d'attente, renouvellements — il n'y a aucune requête, et FF_LOCALE vaudrait la langue par défaut pour tout le monde. C'est pourquoi la préférence de langue est sur le profil (access_users.locale / access_users.ID_lang, voir 07 §3) et est lue par les helpers de library/gallery/common/language_preference.php :

HelperQuand
language_pref_for_user($ID_user)on a l'ID : emails, notifications, PDF, SMS générés par cron/job
language_pref_for_email($email)on n'a que l'adresse ; renvoie null si elle est inconnue ou si plusieurs comptes avec cette adresse ont des préférences différentes

Ordre : profil du destinataire → langue de la requête (seulement si synchrone) → défaut.

  • process_mail() l'applique tout seul : si la structure ne passe pas de "lang" explicite, il la déduit du premier destinataire avec language_pref_for_email(). Un "lang" passé par l'appelant l'emporte toujours.
  • Mailer::setLang($code) fixe la langue de composition : les codes {_…} du template, l'objet quand c'est un code du dictionnaire, les chaînes de PHPMailer ; null revient à FF_LOCALE. Les codes du template sont traduits par loadTemplateFile() (vendor/wolfgan/mailer/Mailer.php) avant que le texte arrive à ffTemplate, qui de lui-même utiliserait toujours FF_LOCALE : jusqu'à la 3.0.3 c'est ce qui se passait, et depuis un cron le corps partait dans la langue par défaut même avec setLang(). ⚠️ Mailer est un singleton : qui fixe la langue doit la refixer à chaque envoi, sinon l'envoi suivant en hérite.
  • L'objet n'est cherché dans le dictionnaire que s'il est un code, c'est-à-dire sans espaces. Un objet déjà rédigé reste tel quel : le chercher le faisait insérer comme entrée de substitution dans ff_international, et avec un code ou une date dedans c'était une nouvelle ligne à chaque envoi. Qui veut un objet traduit le compose dans la langue du destinataire, comme hook.php pour l'activation et la récupération (svc_mail_act_subject, svc_mail_rec_subject, langue issue de language_pref_for_email(), la même qu'utilise le Notifier).
  • Notifier regroupe les destinataires email par langue et fait un envoi par groupe (voir §3).

La préférence ne s'écrit que par un choix explicite depuis le sélecteur de langue (?lang=), voir 12 — Cache, §Multilingue.

La règle des images

Le logo dans les emails est toujours un PNG. Jamais un SVG : les clients de messagerie ne l'affichent pas.

Sur comment il arrive, en revanche, c'est le relais qui décide. Historiquement le logo était joint et référencé par cid:, parce que les clients bloquent les images distantes et qu'un logo par URL, pour une partie des destinataires, n'est pas de logo du tout. Mais certains relais (JoeSMTP, Aruba) rejettent le message entier s'il contient une pièce jointe — 550 … Attachments are not supported — et un logo invisible vaut quand même mieux qu'un email qui ne part pas.

C'est pourquoi Mailer par défaut réécrit les références cid:<fichier> en URL absolues vers WWW_LINK_ABSOLUTE : ces fichiers, le site les sert déjà, ils sont dans themes/<thème>/contents/email/<template>/images/. Là où le relais accepte les pièces jointes et qu'on préfère le logo garanti, il suffit de define("MAILER_EMBED_IMAGES", true) dans config.remote.php.

Le repli est prudent : si l'URL absolue ne peut pas être déduite — fichier hors de la docroot, WWW_LINK_ABSOLUTE non définie pour cet hôte — l'image reste incorporée comme avant.

Les pièces jointes

Même raison, même traitement : par défaut Mailer ne joint pas les fichiers, mais ajoute à la fin du corps (HTML et texte) la liste des liens. Les uploads passent par CM_SHOWFILES, ainsi dans un email qui circule hors du site n'apparaît pas le vrai chemin du dossier ; les fichiers placés à côté du template (.../attach/) passent par URL directe.

Si l'adresse ne peut pas être déduite le fichier reste vraiment joint : retirer la pièce jointe sans en donner l'adresse reviendrait à envoyer un email tronqué. Pour revenir aux vraies pièces jointes : define("MAILER_EMBED_ATTACHMENTS", true).

D'autres règles qu'on apprend en envoyant

  • L'expéditeur doit appartenir au domaine qui envoie (SPF/DKIM). Un From: avec le domaine du destinataire est le moyen le plus rapide de finir en spam.
  • Un registre des envois est un anti-doublon, pas un historique. Avant d'envoyer une communication automatique on vérifie si elle a déjà été envoyée pour cette clé (destinataire, type, période) ; la contrainte unique sur la table est plus fiable qu'un comptage. C'est pourquoi le registre ne s'élague pas (voir 05 §6).
  • Les emails système du module auth (activation, récupération du mot de passe) partent de leur côté : si le projet route tout le reste sur son propre relais, ces deux-là sont à considérer à part.
  • Aperçu avant l'envoi : contents/emailpreviewer/ + /srv/email-preview servent à regarder le message rendu sans l'envoyer. Les utiliser est bien plus rapide que de s'envoyer des emails de test.

La bibliothèque : PHPMailer 7 avec les noms de la 5.2

library/phpmailer/ est PHPMailer 7.1.1 (src/, espace de noms PHPMailer\PHPMailer). Jusqu'à la 3.1.0 c'était la 5.2.14, de 2015, avec les failles connues du transport mail() (CVE-2016-10033, CVE-2016-10045) et sans prise en charge de PHP 8. La plateforme continue de la charger avec les chemins et les classes d'alors — autoload.php, cm/autoload.php, library/gallery/process/mail.php et vendor/wolfgan/mailer/Mailer.php font un require de class.phpmailer.php, class.smtp.php… et new phpmailer() — et un site peut faire de même : class.phpmailer.php, class.smtp.php et class.pop3.php sont des adaptateurs qui définissent PHPMailer, phpmailerException, SMTP et POP3 comme alias des classes de la 7. Les propriétés et méthodes utilisées par la plateforme y sont toutes ; setLanguage() est statique dans la 7, et l'appeler sur une instance fonctionne comme avant. Il n'y a plus l'OAuth de la 5.2 (PHPMailerOAuth, PHPMailerOAuthGoogle), EasyPeasyICS ni NTLM : leurs fichiers restent vides parce que les chargeurs les requièrent. Du code nouveau peut utiliser directement \PHPMailer\PHPMailer\PHPMailer.

L'abstraction Mailer

Mailer::getInstance() offre une API objet (setTitle, setMessage, addAddress, addAttach, addUsers, addGroups, addActions, renderPreview, send) avec des services remplaçables (email_localhost, email_sparkpost) et le chargement du template depuis le thème. C'est le moyen d'envoyer à des utilisateurs et groupes du CMS plutôt qu'à des adresses. Dans le dépôt il est utilisé surtout via Notifier.

3. Notifications in-app

vendor/hcore/notifier/Notifier.php est un moteur de notification multicanal et multidestinataire. C'est la seule copie : le CMS le charge depuis vendor/ via COMPOSER_PATH (les anciennes copies dans library/classes/ et library/gallery/classes/ ont été supprimées parce que personne ne les chargeait).

Notifier::getInstance(array("sms", "email"))
    ->send($message, $users, $groups, $title, $type, $media, $actions, $schedule, $expire, $referer);

Ce qu'il sait faire, d'après ses méthodes :

MéthodeCapacité
setUsers() / setGroups()destinataires par utilisateur ou par groupe du CMS
setMessage($msg, $title, $type, $schedule, $expire, $media, $actions, $referer)texte, type, programmation, expiration, média joint, actions (boutons)
setSchedule() / setExpire() / setTimer()quand elle apparaît et quand elle cesse d'apparaître
read() / update()lecture et mise à jour de l'état
delivered()marque comme livrées
response($keys)payload pour le front-end
sendMail()le canal email de la notification : un envoi par langue des destinataires, avec Mailer::setLang()
setDomain(), setPage(), setUrl(), setVisitor()met la notification en contexte

Le front-end les récupère depuis le bus des services : /srv/request avec l'entrée notify appelle Notifier::response(), et notifyDelivered appelle Notifier::delivered() (voir 03 §3). C'est le mécanisme qui permet à une page en cache d'afficher quand même les notifications de l'utilisateur.

L'UI est dans vendor/hcore/notifier/widgets/notifier/. La gestion depuis le backend est /restricted/notify.

4. Push et SMS

Ce sont des drivers du Notifier, dans vendor/hcore/notifier/services/ :

FichierCanalService (espace Services)Champs
push_onesignal.phppush via OneSignalnotification.onesignalcode (App ID), api_key (clé REST), safari
sms_joesmtp.phpSMS via JoeSMTP (/api/1.0/sms-send)sms.joesmtphost (vide = joesmtp.it), client_id, client_secret, from
sms_twilio.phpSMS via Twilio (REST)sms.twiliosid, token, from

Les identifiants se saisissent depuis l'espace Services du backend (ou depuis l'assistant, étape Services) : ce sont des lignes dans cm_mod_security_domains_fields. Pour le push, les constantes NOTIFY_ONESIGNAL_APP_ID / NOTIFY_ONESIGNAL_API_KEY valent encore comme repli. Voir 10.

Notifier::getInstance("sms")->send("Votre code est 123456", "+393331234567");
Notifier::getInstance("push")->send(array(
    "title" => "Cours confirmé", "message" => "On vous attend à 18 h", "actions" => array("/area-utente")
), array($ID_user));
  • Destinataires. Un téléphone n'est reconnu qu'avec le préfixe + : un numéro nu serait pris pour un ID utilisateur. Le normaliser d'abord avec Notifier::normalizeTel($tel) (E.164, +39 si le préfixe manque). Le push s'adresse par ID utilisateur du CMS ; les groupes ne sont pas pris en charge.
  • Quel fournisseur SMS. Sans service explicite on utilise le premier configuré : JoeSMTP, puis Twilio. Pour en forcer un : Notifier::getInstance(array("sms" => "twilio")).
  • Langue. Pour SMS et push le texte est composé par l'appelant, et personne ne le traduit : le regroupement par langue ne vaut que pour le canal email (§2). Si le message part d'un cron, déduire la langue avec language_pref_for_user($ID_user) avant de composer le texte.
  • Résultat. send() renvoie le résultat du driver : status "0" s'il est parti, sinon status et error, et l'échec finit dans le log notifier_error. JoeSMTP distingue sent de pending : dans le second cas le message est dans leur file et c'est leur cron qui le réessaie.
  • Push, côté navigateur. Avec enable et code, le service notification.onesignal injecte le Web SDK v16 dans chaque page et sert depuis la racine le service worker /OneSignalSDKWorker.js. L'utilisateur connecté est lié à son abonnement par OneSignal.login(<ID utilisateur>) : l'ID est demandé par le navigateur à /OneSignalIdentity (Cache-Control: no-store), jamais écrit dans le HTML, qui peut finir dans le cache partagé. À la déconnexion suit OneSignal.logout(). Prompt, cloche et textes se configurent depuis le tableau de bord OneSignal (Settings → Web → Typical Site) ; la langue de la page passe par User.setLanguage.
  • Push, envoi. POST https://api.onesignal.com/notifications avec Authorization: Key <api_key>, destinataires dans include_aliases.external_id. Un envoi à des utilisateurs qui ne se sont jamais abonnés réussit quand même (aucune erreur, id vide) : ce n'est pas une panne.

5. Ajouter un canal

Le modèle des services de Notifier et Mailer est le même : un fichier par canal, qui déclare une const TYPE et implémente l'envoi. Un driver push/SMS du Notifier expose isConfigured() (statique) et send($payload), qui reçoit Notifier::getPayload() et renvoie array("status" => "0" | code, "error" => …). Pour un nouveau fournisseur :

  1. copier le driver le plus proche (sms_joesmtp.php pour une API à token, sms_twilio.php pour une API en Basic auth, email_localhost.php pour SMTP) et, si c'est un SMS, l'ajouter à la liste de controller_sms() : vgCommon::loadControllers n'enregistre qu'un driver par type comme défaut, c'est le Notifier qui choisit ;
  2. lire les identifiants depuis l'espace Services avec Notifier::serviceConfig("<service>"), jamais les câbler dans le fichier ; pour les appels utiliser Notifier::http(), qui vérifie le certificat ;
  3. distinguer explicitement échoué de pris en charge : presque tous les fournisseurs répondent 202 et livrent plus tard ;
  4. si le fournisseur expose des webhooks d'état, les brancher comme endpoint /srv/<fournisseur>/webhook — modèle, secret et idempotence dans 03 §2. C'est le seul moyen de savoir si un message est vraiment arrivé ;
  5. si le fournisseur le permet, passer l'URL de callback par message au lieu de la configurer dans le tableau de bord.

Corrélation. Au moment de l'envoi, passer au fournisseur une référence propre (X-Entity-Ref-ID, tag, correlation_id du type entite_x|detail_y) et la lire dans le webhook. Sans elle, quand les rapports arrivent on ne sait pas à quoi ils appartiennent, et on ne le reconstitue pas après coup.

6. Pièges déjà payés

  • 550 … Attachments are not supported ne parle ni de taille ni de MIME : ce relais rejette toute pièce jointe — images inline cid: comprises — et rejette le message entier, qui donc ne part pas du tout. Comment Mailer le traite : §2, « La règle des images ».
  • Les statistiques d'un canal ne se mettent pas à jour parce que le chemin de ce canal écrit dans une table différente de celle que lit le tableau de bord. Avant d'accuser le webhook, vérifier quelle table lit l'écran.
  • Pourcentages au-delà de 100 % : les compteurs sont incrémentés à chaque événement, et les fournisseurs répètent les événements. L'incrément doit se faire seulement quand le flag par destinataire passe de 0→1 (AND flag = 0 dans le WHERE + contrôle de affectedRows()).
  • Emoji tronqués ou message vide : les tables historiques du CMS sont en utf8mb3. Les nouvelles tables contenant du texte libre doivent être créées en utf8mb4, et la connexion réglée en conséquence.
  • Un From: sans expéditeur approuvé chez le fournisseur fait échouer l'envoi avec une erreur qui ne parle pas d'expéditeurs. Le vérifier en premier.
  • Notifier::send() et Mailer::send() ne renvoient pas un tableau de résultat. Avec un seul service actif ils renvoient le bool de PHPMailer si l'envoi réussit et la chaîne du message s'il échoue (Notifier::getResult() et Mailer::getResult() renvoient à vgCommon::isError()) ; le tableau n'arrive qu'avec plusieurs services. Lire $esito["error"] sans is_array() était un warning en PHP 7 et c'est un fatal depuis PHP 8 — ainsi une panne de messagerie se présente comme un 500 au lieu d'un message. La bonne forme :
    $esito = Notifier::getInstance("email")->send($params);
    $errore = (is_array($esito) ? ($esito["error"] ?? null) : $esito);

    Le message technique de l'envoi échoué finit de toute façon dans le log error_critical, écrit par vgCommon::isError() : c'est là qu'on cherche la vraie raison.