Email, notifiche, SMS e push
Il CMS sa spedire: email transazionali con template e allegati, notifiche in-app, SMS e push tramite provider. Non tutto è cablato allo stesso livello: questa pagina dice cosa è pronto, cosa è presente-ma-da-configurare e cosa è impalcatura upstream.
1. Panoramica
| Canale | Motore | Stato nel repo |
|---|---|---|
| Email transazionale | process_mail() + PHPMailer (SMTP) | in esercizio: registrazione, attivazione, recupero password |
| Email (astrazione a servizi) | Mailer (vendor/wolfgan/mailer/) | presente; servizi email_localhost (SMTP) e email_sparkpost |
| Notifiche in-app | Notifier (vendor/hcore/notifier/) + sezione backend /restricted/notify | presente, con widget e applet |
| Push browser/app | driver push_onesignal + servizio notification.onesignal | pronto, richiede App ID e chiave REST |
| SMS | driver sms_joesmtp / sms_twilio + servizi sms.joesmtp / sms.twilio | pronto, richiede credenziali |
| Secondo fattore al login | Auth::login + canale email o SMS del Notifier | spento di default (AUTH_2FA), vedi 08 |
| Anteprima email | contents/emailpreviewer/, /srv/email-preview (regola in modules/cms-common) | presente |
2. Email transazionali
Configurazione
L'installer scrive in 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", "");
Le legge vendor/wolfgan/mailer/services/email_localhost.php (e l'equivalente sparkpost). Il wizard fa un invio di prova durante l'installazione, con client SMTP standalone (SSL 465 / STARTTLS 587 / plain): la posta si verifica prima di finire, non al primo utente che si registra.
Inviare
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 costruisce una struttura con tema, dominio, lingua e parametri SMTP, poi risolve il template e spedisce. I template stanno in themes/<tema>/contents/email/ — nel repo, auth/activation_code.html, auth/recover_code.html e auth/account_code.html (codice del 2FA), con le immagini in email/images/. I loro testi sono codici del dizionario (svc_mail_*), quindi l'email esce nella lingua di composizione (sotto); fino alla 3.0.3 erano scritti in italiano dentro il file.
In che lingua esce una email
La lingua del destinatario, non quella della richiesta. FF_LOCALE va bene per gli invii sincroni (chi riceve è chi ha appena cliccato), ma in un cron o in un job asincrono — promemoria, scadenze, waitlist, rinnovi — non c'è nessuna richiesta, e FF_LOCALE varrebbe il default per tutti. Per questo la preferenza di lingua sta sul profilo (access_users.locale / access_users.ID_lang, vedi 07 §3) e la leggono gli helper di library/gallery/common/language_preference.php:
| Helper | Quando |
|---|---|
language_pref_for_user($ID_user) | si ha l'ID: email, notifiche, PDF, SMS generati da cron/job |
language_pref_for_email($email) | si ha solo l'indirizzo; risponde null se è ignoto o se più account con quell'indirizzo hanno preferenze diverse |
Ordine: profilo del destinatario → lingua della richiesta (solo se sincrona) → default.
process_mail()lo applica da sé: se la struttura non passa una"lang"esplicita, la ricava dal primo destinatario conlanguage_pref_for_email(). Una"lang"passata dal chiamante comanda sempre.Mailer::setLang($code)fissa la lingua di composizione: i codici{_…}del template, l'oggetto quando è un codice del dizionario, le stringhe di PHPMailer;nulltorna aFF_LOCALE. I codici del template li traduceloadTemplateFile()(vendor/wolfgan/mailer/Mailer.php) prima di passare il testo affTemplate, che da sé userebbe sempreFF_LOCALE: fino alla 3.0.3 succedeva questo, e da un cron il corpo usciva nella lingua predefinita anche consetLang(). ⚠️Mailerè un singleton: chi imposta la lingua deve reimpostarla a ogni invio, altrimenti l'invio successivo la eredita.- L'oggetto si cerca nel dizionario solo se è un codice, cioè senza spazi. Un oggetto già scritto resta com'è: cercarlo lo faceva inserire come segnaposto in
ff_international, e con un codice o una data dentro era una riga nuova a ogni invio. Chi vuole l'oggetto tradotto lo compone nella lingua del destinatario, comehook.phpper attivazione e recupero (svc_mail_act_subject,svc_mail_rec_subject, lingua dalanguage_pref_for_email(), la stessa che usa ilNotifier). Notifierraggruppa i destinatari email per lingua e fa un invio per gruppo (vedi §3).
La preferenza si scrive solo con una scelta esplicita dal selettore lingua (?lang=), vedi 12 — Cache, §Multilingua.
La regola sulle immagini
Il logo nelle email è sempre un PNG. Mai un SVG: i client di posta non lo renderizzano.
Su come arriva, invece, decide il relay. Storicamente il logo si allegava e si referenziava con cid:, perché i client bloccano le immagini remote e un logo via URL, per una parte dei destinatari, è nessun logo. Ma certi relay (JoeSMTP, Aruba) rifiutano il messaggio intero se contiene una parte allegata — 550 … Attachments are not supported — e un logo che non si vede è comunque meglio di una mail che non parte.
Per questo Mailer di default riscrive i riferimenti cid:<file> come URL assoluti verso WWW_LINK_ABSOLUTE: quei file il sito li serve già, stanno in themes/<tema>/contents/email/<template>/images/. Dove il relay accetta gli allegati e si preferisce il logo garantito, basta define("MAILER_EMBED_IMAGES", true) in config.remote.php.
Il ripiego è prudente: se l'URL assoluto non si ricava — file fuori dalla docroot, WWW_LINK_ABSOLUTE non definita per quell'host — l'immagine resta incorporata come prima.
Gli allegati
Stessa ragione, stesso trattamento: di default Mailer non allega i file, ma mette in coda al corpo (HTML e testo) l'elenco dei link. Gli upload passano da CM_SHOWFILES, così in una mail che gira fuori dal sito non compare il percorso vero della cartella; i file che stanno accanto al template (.../attach/) vanno per URL diretto.
Se l'indirizzo non si ricava il file resta allegato davvero: togliere l'allegato senza darne l'indirizzo vorrebbe dire spedire una mail monca. Per tornare agli allegati veri: define("MAILER_EMBED_ATTACHMENTS", true).
Altre regole che si imparano spedendo
- Il mittente deve essere del dominio che spedisce (SPF/DKIM). Un
From:con il dominio del destinatario è il modo più veloce per finire in spam. - Un registro degli invii è un anti-duplicato, non uno storico. Prima di spedire una comunicazione automatica si verifica se è già stata mandata per quella chiave
(destinatario, tipo, periodo); il vincolo unico sulla tabella è più affidabile di un conteggio. Per questo il registro non si pota (vedi 05 §6). - Le email di sistema del modulo
auth(attivazione, recupero password) escono per conto loro: se il progetto instrada tutto il resto su un relay proprio, quelle due vanno considerate a parte. - Anteprima prima dell'invio:
contents/emailpreviewer/+/srv/email-previewservono a guardare il messaggio renderizzato senza spedirlo. Usarli è molto più veloce che mandarsi email di prova.
La libreria: PHPMailer 7 con i nomi della 5.2
library/phpmailer/ è PHPMailer 7.1.1 (src/, spazio dei nomi PHPMailer\PHPMailer). Fino alla 3.1.0 era la 5.2.14, del 2015, con le falle note del trasporto mail() (CVE-2016-10033, CVE-2016-10045) e senza supporto per PHP 8. La piattaforma continua a caricarla con i percorsi e le classi di allora — autoload.php, cm/autoload.php, library/gallery/process/mail.php e vendor/wolfgan/mailer/Mailer.php fanno require di class.phpmailer.php, class.smtp.php… e new phpmailer() — e così può fare un sito: class.phpmailer.php, class.smtp.php e class.pop3.php sono adattatori che definiscono PHPMailer, phpmailerException, SMTP e POP3 come alias delle classi della 7. Proprietà e metodi usati dalla piattaforma ci sono tutti; setLanguage() nella 7 è statico, e chiamarlo su un'istanza funziona come prima. Non ci sono più l'OAuth della 5.2 (PHPMailerOAuth, PHPMailerOAuthGoogle), EasyPeasyICS e NTLM: i loro file restano vuoti perché i caricatori li richiedono. Codice nuovo può usare direttamente \PHPMailer\PHPMailer\PHPMailer.
L'astrazione Mailer
Mailer::getInstance() offre un'API a oggetti (setTitle, setMessage, addAddress, addAttach, addUsers, addGroups, addActions, renderPreview, send) con servizi sostituibili (email_localhost, email_sparkpost) e caricamento del template dal tema. È la strada per spedire a utenti e gruppi del CMS invece che a indirizzi. Nel repo è usata soprattutto attraverso Notifier.
3. Notifiche in-app
vendor/hcore/notifier/Notifier.php è un motore di notifica multi-canale e multi-destinatario. È l'unica copia: il CMS lo carica da vendor/ tramite COMPOSER_PATH (le vecchie copie in library/classes/ e library/gallery/classes/ sono state rimosse perché nessuno le caricava).
Notifier::getInstance(array("sms", "email"))
->send($message, $users, $groups, $title, $type, $media, $actions, $schedule, $expire, $referer);
Cosa sa fare, guardando i metodi:
| Metodo | Capacità |
|---|---|
setUsers() / setGroups() | destinatari per utente o per gruppo del CMS |
setMessage($msg, $title, $type, $schedule, $expire, $media, $actions, $referer) | testo, tipo, programmazione, scadenza, media allegato, azioni (bottoni) |
setSchedule() / setExpire() / setTimer() | quando appare e quando smette di apparire |
read() / update() | lettura e aggiornamento dello stato |
delivered() | marca come consegnate |
response($keys) | payload per il frontend |
sendMail() | il canale email della notifica: un invio per lingua dei destinatari, con Mailer::setLang() |
setDomain(), setPage(), setUrl(), setVisitor() | contestualizza la notifica |
Il frontend le raccoglie dal bus dei servizi: /srv/request con la voce notify chiama Notifier::response(), e notifyDelivered chiama Notifier::delivered() (vedi 03 §3). È il meccanismo che permette a una pagina in cache di mostrare comunque le notifiche dell'utente.
La UI è in vendor/hcore/notifier/widgets/notifier/. La gestione da backend è /restricted/notify.
4. Push e SMS
Sono driver del Notifier, in vendor/hcore/notifier/services/:
| File | Canale | Servizio (area Servizi) | Campi |
|---|---|---|---|
push_onesignal.php | push via OneSignal | notification.onesignal | code (App ID), api_key (chiave REST), safari |
sms_joesmtp.php | SMS via JoeSMTP (/api/1.0/sms-send) | sms.joesmtp | host (vuoto = joesmtp.it), client_id, client_secret, from |
sms_twilio.php | SMS via Twilio (REST) | sms.twilio | sid, token, from |
Le credenziali si inseriscono dall'area Servizi del backend (o dal wizard, step Servizi): sono righe in cm_mod_security_domains_fields. Per il push valgono ancora, come ripiego, le costanti NOTIFY_ONESIGNAL_APP_ID / NOTIFY_ONESIGNAL_API_KEY. Vedi 10.
Notifier::getInstance("sms")->send("Il tuo codice è 123456", "+393331234567");
Notifier::getInstance("push")->send(array(
"title" => "Lezione confermata", "message" => "Ti aspettiamo alle 18", "actions" => array("/area-utente")
), array($ID_user));
- Destinatari. Un telefono è riconosciuto solo con il prefisso
+: un numero nudo verrebbe preso per un ID utente. Normalizzarlo prima conNotifier::normalizeTel($tel)(E.164,+39se manca il prefisso). Il push si indirizza per ID utente del CMS; i gruppi non sono supportati. - Quale provider SMS. Senza servizio esplicito si usa il primo configurato: JoeSMTP, poi Twilio. Per forzarne uno:
Notifier::getInstance(array("sms" => "twilio")). - Lingua. Per SMS e push il testo lo compone il chiamante, e nessuno lo traduce: il raggruppamento per lingua vale solo per il canale email (§2). Se il messaggio parte da un cron, ricavare la lingua con
language_pref_for_user($ID_user)prima di comporre il testo. - Esito.
send()restituisce il risultato del driver:status"0"se è partito, altrimentistatuseerror, e il fallimento finisce nel lognotifier_error. JoeSMTP distinguesentdapending: nel secondo caso il messaggio è in coda da loro e lo ritenta il loro cron. - Push, lato browser. Con
enableecodeil servizionotification.onesignalinietta il Web SDK v16 in ogni pagina e serve dalla radice il service worker/OneSignalSDKWorker.js. L'utente loggato viene collegato alla sua iscrizione conOneSignal.login(<ID utente>): l'ID lo chiede il browser a/OneSignalIdentity(Cache-Control: no-store), mai scritto nell'HTML, che può finire nella cache condivisa. All'uscita segueOneSignal.logout(). Prompt, campanella e testi si configurano dalla dashboard OneSignal (Settings → Web → Typical Site); la lingua della pagina passa conUser.setLanguage. - Push, invio.
POST https://api.onesignal.com/notificationsconAuthorization: Key <api_key>, destinatari ininclude_aliases.external_id. Un invio a utenti che non si sono mai iscritti riesce comunque (nessun errore,idvuoto): non è un guasto.
5. Aggiungere un canale
Il pattern dei servizi di Notifier e Mailer è lo stesso: un file per canale, che dichiara una const TYPE e implementa l'invio. Un driver push/SMS del Notifier espone isConfigured() (statico) e send($payload), che riceve Notifier::getPayload() e restituisce array("status" => "0" | codice, "error" => …). Per un provider nuovo:
- copiare il driver più vicino (
sms_joesmtp.phpper un'API con token,sms_twilio.phpper una con Basic auth,email_localhost.phpper SMTP) e, se è un SMS, aggiungerlo alla lista dicontroller_sms():vgCommon::loadControllersregistra un solo driver per tipo come predefinito, la scelta la fa ilNotifier; - leggere le credenziali dall'area Servizi con
Notifier::serviceConfig("<servizio>"), mai cablarle nel file; per le chiamate usareNotifier::http(), che verifica il certificato; - distinguere in modo esplicito fallito da preso in carico: quasi tutti i provider rispondono 202 e consegnano dopo;
- se il provider espone i webhook di stato, agganciarli come endpoint
/srv/<provider>/webhook— pattern, secret e idempotenza in 03 §2. È l'unico modo di sapere se un messaggio è davvero arrivato; - se il provider lo consente, passare l'URL di callback per singolo messaggio invece di configurarlo nella dashboard.
Correlazione. Al momento dell'invio, passare al provider un riferimento proprio (
X-Entity-Ref-ID,tag,correlation_iddel tipoentita_x|dettaglio_y) e leggerlo nel webhook. Senza, quando i report arrivano non si sa a cosa appartengono, e non si ricostruisce a posteriori.
6. Trappole già pagate
550 … Attachments are not supportednon parla di dimensioni né di MIME: quel relay rifiuta qualsiasi parte allegata — immagini inlinecid:comprese — e rifiuta il messaggio intero, che quindi non parte affatto. Come lo trattaMailer: §2, «La regola sulle immagini».- Le statistiche di un canale non si aggiornano perché il percorso di quel canale scrive su una tabella diversa da quella che la dashboard legge. Prima di dare la colpa al webhook, verificare quale tabella legge la schermata.
- Percentuali oltre il 100%: i contatori vengono incrementati a ogni evento, e i provider ripetono gli eventi. L'incremento deve avvenire solo quando il flag per-destinatario transisce 0→1 (
AND flag = 0nellaWHERE+ controllo diaffectedRows()). - Emoji troncate o messaggio vuoto: le tabelle storiche del CMS sono
utf8mb3. Le tabelle nuove che contengono testo libero vanno createutf8mb4, e la connessione va impostata di conseguenza. - Un
From:senza mittente approvato presso il provider fa fallire l'invio con un errore che non parla di mittenti. Verificarlo per primo. Notifier::send()eMailer::send()non tornano un array di esito. Con un solo servizio attivo tornano ilbooldi PHPMailer se l'invio riesce e la stringa del messaggio se fallisce (Notifier::getResult()eMailer::getResult()rimandano avgCommon::isError()); l'array arriva solo con più servizi. Leggere$esito["error"]senzais_array()era un warning in PHP 7 ed è un fatal da PHP 8 — così un guasto di posta si presenta come 500 anziché come messaggio. La forma giusta:$esito = Notifier::getInstance("email")->send($params); $errore = (is_array($esito) ? ($esito["error"] ?? null) : $esito);Il messaggio tecnico dell'invio fallito finisce comunque nel log
error_critical, scritto davgCommon::isError(): è lì che si cerca la ragione vera.