Vai al contenuto
JoeCMS Scarica 3.1.5
Manuale · 06

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

CanaleMotoreStato nel repo
Email transazionaleprocess_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-appNotifier (vendor/hcore/notifier/) + sezione backend /restricted/notifypresente, con widget e applet
Push browser/appdriver push_onesignal + servizio notification.onesignalpronto, richiede App ID e chiave REST
SMSdriver sms_joesmtp / sms_twilio + servizi sms.joesmtp / sms.twiliopronto, richiede credenziali
Secondo fattore al loginAuth::login + canale email o SMS del Notifierspento di default (AUTH_2FA), vedi 08
Anteprima emailcontents/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:

HelperQuando
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 con language_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; null torna a FF_LOCALE. I codici del template li traduce loadTemplateFile() (vendor/wolfgan/mailer/Mailer.php) prima di passare il testo a ffTemplate, che da sé userebbe sempre FF_LOCALE: fino alla 3.0.3 succedeva questo, e da un cron il corpo usciva nella lingua predefinita anche con setLang(). ⚠️ 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, come hook.php per attivazione e recupero (svc_mail_act_subject, svc_mail_rec_subject, lingua da language_pref_for_email(), la stessa che usa il Notifier).
  • Notifier raggruppa 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-preview servono 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:

MetodoCapacità
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/:

FileCanaleServizio (area Servizi)Campi
push_onesignal.phppush via OneSignalnotification.onesignalcode (App ID), api_key (chiave REST), safari
sms_joesmtp.phpSMS via JoeSMTP (/api/1.0/sms-send)sms.joesmtphost (vuoto = joesmtp.it), client_id, client_secret, from
sms_twilio.phpSMS via Twilio (REST)sms.twiliosid, 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 con Notifier::normalizeTel($tel) (E.164, +39 se 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, altrimenti status e error, e il fallimento finisce nel log notifier_error. JoeSMTP distingue sent da pending: nel secondo caso il messaggio è in coda da loro e lo ritenta il loro cron.
  • Push, lato browser. Con enable e code il servizio notification.onesignal inietta il Web SDK v16 in ogni pagina e serve dalla radice il service worker /OneSignalSDKWorker.js. L'utente loggato viene collegato alla sua iscrizione con OneSignal.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 segue OneSignal.logout(). Prompt, campanella e testi si configurano dalla dashboard OneSignal (Settings → Web → Typical Site); la lingua della pagina passa con User.setLanguage.
  • Push, invio. POST https://api.onesignal.com/notifications con Authorization: Key <api_key>, destinatari in include_aliases.external_id. Un invio a utenti che non si sono mai iscritti riesce comunque (nessun errore, id vuoto): 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:

  1. copiare il driver più vicino (sms_joesmtp.php per un'API con token, sms_twilio.php per una con Basic auth, email_localhost.php per SMTP) e, se è un SMS, aggiungerlo alla lista di controller_sms(): vgCommon::loadControllers registra un solo driver per tipo come predefinito, la scelta la fa il Notifier;
  2. leggere le credenziali dall'area Servizi con Notifier::serviceConfig("<servizio>"), mai cablarle nel file; per le chiamate usare Notifier::http(), che verifica il certificato;
  3. distinguere in modo esplicito fallito da preso in carico: quasi tutti i provider rispondono 202 e consegnano dopo;
  4. 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;
  5. 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_id del tipo entita_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 supported non parla di dimensioni né di MIME: quel relay rifiuta qualsiasi parte allegata — immagini inline cid: comprese — e rifiuta il messaggio intero, che quindi non parte affatto. Come lo tratta Mailer: §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 = 0 nella WHERE + controllo di affectedRows()).
  • Emoji troncate o messaggio vuoto: le tabelle storiche del CMS sono utf8mb3. Le tabelle nuove che contengono testo libero vanno create utf8mb4, 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() e Mailer::send() non tornano un array di esito. Con un solo servizio attivo tornano il bool di PHPMailer se l'invio riesce e la stringa del messaggio se fallisce (Notifier::getResult() e Mailer::getResult() rimandano a vgCommon::isError()); l'array arriva solo con più servizi. Leggere $esito["error"] senza is_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 da vgCommon::isError(): è lì che si cerca la ragione vera.