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
| Canal | Moteur | État dans le dépôt |
|---|---|---|
| Email transactionnel | process_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-app | Notifier (vendor/hcore/notifier/) + section backend /restricted/notify | présent, avec widget et applet |
| Push navigateur/app | driver push_onesignal + service notification.onesignal | prêt, App ID et clé REST nécessaires |
| SMS | drivers sms_joesmtp / sms_twilio + services sms.joesmtp / sms.twilio | prêt, identifiants nécessaires |
| Second facteur à la connexion | Auth::login + canal email ou SMS du Notifier | désactivé par défaut (AUTH_2FA), voir 08 |
| Aperçu des emails | contents/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 :
| Helper | Quand |
|---|---|
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 aveclanguage_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 ;nullrevient àFF_LOCALE. Les codes du template sont traduits parloadTemplateFile()(vendor/wolfgan/mailer/Mailer.php) avant que le texte arrive àffTemplate, qui de lui-même utiliserait toujoursFF_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 avecsetLang(). ⚠️Mailerest 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, commehook.phppour l'activation et la récupération (svc_mail_act_subject,svc_mail_rec_subject, langue issue delanguage_pref_for_email(), la même qu'utilise leNotifier). Notifierregroupe 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-previewservent à 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éthode | Capacité |
|---|---|
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/ :
| Fichier | Canal | Service (espace Services) | Champs |
|---|---|---|---|
push_onesignal.php | push via OneSignal | notification.onesignal | code (App ID), api_key (clé REST), safari |
sms_joesmtp.php | SMS via JoeSMTP (/api/1.0/sms-send) | sms.joesmtp | host (vide = joesmtp.it), client_id, client_secret, from |
sms_twilio.php | SMS via Twilio (REST) | sms.twilio | sid, 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 avecNotifier::normalizeTel($tel)(E.164,+39si 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, sinonstatuseterror, et l'échec finit dans le lognotifier_error. JoeSMTP distinguesentdepending: dans le second cas le message est dans leur file et c'est leur cron qui le réessaie. - Push, côté navigateur. Avec
enableetcode, le servicenotification.onesignalinjecte le Web SDK v16 dans chaque page et sert depuis la racine le service worker/OneSignalSDKWorker.js. L'utilisateur connecté est lié à son abonnement parOneSignal.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 suitOneSignal.logout(). Prompt, cloche et textes se configurent depuis le tableau de bord OneSignal (Settings → Web → Typical Site) ; la langue de la page passe parUser.setLanguage. - Push, envoi.
POST https://api.onesignal.com/notificationsavecAuthorization: Key <api_key>, destinataires dansinclude_aliases.external_id. Un envoi à des utilisateurs qui ne se sont jamais abonnés réussit quand même (aucune erreur,idvide) : 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 :
- copier le driver le plus proche (
sms_joesmtp.phppour une API à token,sms_twilio.phppour une API en Basic auth,email_localhost.phppour SMTP) et, si c'est un SMS, l'ajouter à la liste decontroller_sms():vgCommon::loadControllersn'enregistre qu'un driver par type comme défaut, c'est leNotifierqui choisit ; - lire les identifiants depuis l'espace Services avec
Notifier::serviceConfig("<service>"), jamais les câbler dans le fichier ; pour les appels utiliserNotifier::http(), qui vérifie le certificat ; - distinguer explicitement échoué de pris en charge : presque tous les fournisseurs répondent 202 et livrent plus tard ;
- 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é ; - 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_iddu typeentite_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 supportedne parle ni de taille ni de MIME : ce relais rejette toute pièce jointe — images inlinecid:comprises — et rejette le message entier, qui donc ne part pas du tout. CommentMailerle 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 = 0dans leWHERE+ contrôle deaffectedRows()). - 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 enutf8mb4, 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()etMailer::send()ne renvoient pas un tableau de résultat. Avec un seul service actif ils renvoient leboolde PHPMailer si l'envoi réussit et la chaîne du message s'il échoue (Notifier::getResult()etMailer::getResult()renvoient àvgCommon::isError()) ; le tableau n'arrive qu'avec plusieurs services. Lire$esito["error"]sansis_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 parvgCommon::isError(): c'est là qu'on cherche la vraie raison.