Moduli e servizi di terze parti
Due meccanismi di estensione, con nomi che si somigliano e scopi diversi: i moduli aggiungono codice, rotte e pagine; i servizi iniettano tag di terze parti (analytics, mappe, font, pixel) configurabili da backend senza toccare il codice.
1. Moduli: codice di progetto fuori da hook.php
Ogni cartella dentro /modules viene caricata automaticamente. La struttura tipica:
modules/<nome>/
├── common.php funzioni del modulo (caricate dal CMS)
├── autoload.php autoloader proprio (opzionale)
├── events.php aggancio agli eventi del ciclo di pagina (opzionale)
├── conf/
│ ├── routing_table.xml rotte del modulo → caricate automaticamente
│ └── mod_restricted.xml voci del backend
├── models/ classi del modulo
├── contents/ pagine del modulo
├── library/
│ ├── job/<nome>.php funzioni job_<nome>() (check_function("job_..."))
│ └── system/<nome>.php funzioni system_<nome>() (check_function("system_..."))
└── themes/ CSS/JS/template del modulo
I moduli presenti nel repo:
| Modulo | Contenuto |
|---|---|
auth | login, registrazione, recupero, attivazione, social (08) |
restricted | il backend: ^/restricted(.*) → /layout$0, ^/admin/settings(.*) → /settings$1 |
cms-common | il modulo di progetto: la regola /srv/(.*) → /applets/services/$1 e models/Sitemap.php |
security | contenuti del modulo di sicurezza |
package-manager | gestione moduli ed estensioni (.zip): upload stile WordPress, auto-migrazione DB e wizard |
Dove mettere il codice di un progetto nuovo: in un modulo, non in
hook.php.hook.phpè codice della piattaforma (~1.900 righe di helper legacy) e l'aggiornamento lo sostituisce: una riga del progetto scritta lì sparisce alla prossima versione. Un modulo ha autoload proprio, si carica da sé, e si può spostare su un altro progetto copiando una cartella.modules/cms-commonè il posto giusto per ciò che è comune, un modulo dedicato per ciò che è del prodotto. Per poche righe (un ascoltatore diAuth::addEvent(), un helper) c'èhook.local.php, accanto ahook.php: lo includehook.phpin fondo, non è nel pacchetto e l'aggiornamento non lo tocca. Un valore da cambiare (dominio,AREA_*,MAX_UPLOAD) va invece nel config.
⚠️ conf/schema.php dentro un modulo non viene letto. Solo library/gallery/settings.php (core) e themes/<tema>/settings.php (progetto) vengono caricati. modules/cms-common/conf/schema.php esiste ed è codice morto: le dichiarazioni di $schema["request"] e $schema["page"] vanno nel tema (vedi 01 §5).
Package Manager: installazione moduli ZIP e auto-migrazione DB
Il modulo package-manager (/admin/pacchetti) fornisce al backend di JoeCMS un'area per caricare archivi ZIP contenenti moduli ed estensioni, gestendo l'intero ciclo di vita:
- Validazione di sicurezza: verifica del file ZIP con blocco dei percorsi pericolosi (path traversal
../o assoluti). - Lettura del descrittore
manifest.json: metadati del modulo, versione minima di JoeCMS richiesta, dipendenze. - Estrazione selettiva: scompatta i componenti nelle rispettive cartelle (
modules/<id>/,contents/,themes/). - Auto-aggiornamento del database: se il manifest specifica
database.schema, esegue automaticamente la DDL SQL tramite la connessione attiva. - Setup Wizard post-installazione: reindirizza opzionalmente al wizard di configurazione percorsi e parametri del modulo.
Autoload per convenzione
check_function() in library/gallery/common.php carica il file giusto dal nome della funzione:
| Prefisso | File cercato |
|---|---|
job_<x> | modules/<mod>/library/job/<x>.php, poi library/gallery/job/<x>.php |
system_<x> | modules/<mod>/library/system/<x>.php, poi library/gallery/system/<x>.php |
mod_<mod>_<x> | modules/<mod>/events.php |
È il motivo per cui in tutto il codice si trova if (check_function("system_qualcosa")) { … }: il file viene incluso solo se serve.
2. I moduli funzionali del CMS
conf/gallery/modules/ contiene sottosistemi completi, ciascuno con configurazione e gestione nel backend:
| Modulo | Cosa fa |
|---|---|
form | costruttore di form: definizione dei campi da backend, selezioni, listini, invio email con template, revisioni, archivio delle compilazioni (manage/, detail.php) |
search | ricerca sui contenuti, con configurazione, gruppi, extra e anteprima |
newsletter | iscrizioni e invii |
calendar | eventi a calendario |
maps | mappe |
share | condivisione social |
tagcloud | nuvola di tag |
videobar, fbalbum, swf | media e gallerie (componenti datati) |
register | registrazione |
shippingprice | costi di spedizione (e-commerce) |
Il modulo form è quello che più spesso fa risparmiare lavoro: un form di contatto, una richiesta di preventivo, un questionario si configurano dal backend — campi, validazioni, email di notifica, elenco delle risposte — senza scrivere una pagina.
E-commerce
C'è un'impalcatura: rotte /user/cart, /user/wishlist, /user/manage, /user/mpay, library/gallery/ecommerce/product_process.php, conf/gallery/manage/ con operazioni e pagamenti, il job reset_carts, library/PayPal/, e le tabelle relative nel seed.
⚠️ È codice upstream non collaudato in questo prototipo. Trattarlo come punto di partenza da verificare, non come funzione pronta.
Pagamenti: il mozzo Payment
Indipendente dall'impalcatura qui sopra: è il posto dove un progetto incassa senza scriversi la propria integrazione. library/payment/Payment.php dichiara cosa vuol dire incassare, i gateway sono driver in library/payment/services/<nome>.php (classe payment<Nome>), e il mozzo se li carica da sé: negli autoloader c'è un caso solo, Payment, sia in autoload.php di radice (lo include l'API) sia in vendor/wolfgan/autoload.php, quello che index.php carica via Composer. Fino alla 1.6.2 il secondo non c'era, e dal sito checkout, webhook e cron dei pagamenti morivano con «Class Payment not found».
$esito = Payment::gateway()->checkout(array(
"riferimento" => "acquisto:1234", // il proprio ID, non quello del gateway
"descrizione" => "Pacchetto 10 lezioni",
"importo_cent" => 18000, // sempre interi in centesimi, mai float
"email" => "anna@esempio.it",
"ritorno_ok" => "https://sito/area/acquisto?esito=ok",
"ritorno_ko" => "https://sito/area/acquisto?esito=annullato",
));
// array(ok, id, url, error): si manda la persona su url
Ogni driver espone checkout() (una tantum), subscribe() (ricorrente), verify() e subscriptionVerify() (stato reale), subscriptionCancel(), refund(), webhookVerify(). verify() risponde sempre nella stessa forma, con uno stato normalizzato: pagato, in_attesa, fallito, rimborsato, annullato (costanti Payment::PAGATO e seguenti). Il gateway si sceglie con Payment::gateway('<nome>'), oppure con la costante PAYMENT_GATEWAY; il valore di partenza è stripe.
- Il webhook innesca, la verità si va a leggere. Del corpo di un webhook non si applica niente: si verifica la firma (
webhookVerify()), si registra l'ID dell'evento per non lavorarlo due volte, si risponde 200. Chi elabora chiamaverify(), che rilegge lo stato dal gateway. Gli eventi arrivano fuori ordine, e se il webhook non arriva un giro di riconciliazione che rilegge gli incassi sospesi basta a far tornare i conti. La ricezione segue il pattern di 03 §2. - Le chiavi stanno nell'area Servizi, servizio
payment.stripe(conf/gallery/services/payment.stripe/):code(pubblicabilepk_…),api_key(segretask_…),webhook_secret(whsec_…),currency(vuoto =eur). Il servizio non inietta niente nella pagina. Fuori dal CMS (cron da riga di comando) o con il servizio spento, il driver ripiega sulle costantiSTRIPE_PUBLIC,STRIPE_SECRET,STRIPE_WEBHOOK_SECRET,STRIPE_CURRENCY. - L'ambiente lo dice la chiave: solo
sk_live_/rk_live_incassano soldi veri (ambiente()rispondelive,testoignoto). Se ci si dimentica di cambiare chiave si resta in prova. - Le date passano dal fuso del sito:
Payment::fuso()usaTIMEZONE(la scrive l'installer nel config), altrimenti il fuso di PHP, e con un valore non valido ripiega su UTC invece di fermare l'incasso. Un driver nuovo converte le date da lì, non da una costante sua. - Prodotti, crediti, ricevute e il registro degli incassi non sono nel mozzo: sono del modulo del sito.
⚠️ Il driver Stripe viene da GDay, dove è in esercizio; nel repository base non c'è un progetto che lo usi.
3. Servizi di terze parti
Un "servizio" è un tag di terze parti configurabile da backend. Struttura:
conf/gallery/services/<nome>/
├── config/index.php definisce i campi configurabili (enable, code, …)
└── index.php inietta il tag a runtime
config/index.php dichiara i tipi dei campi e delega a system_services_modify(), che costruisce la schermata di configurazione:
$type_field["enable"] = "Boolean";
$type_field["code"] = "String";
system_services_modify(basename(ffCommon_dirname(ffCommon_dirname(__FILE__))), $type_field);
index.php legge i valori ($actual_srv) e inietta:
if ($actual_srv["enable"] && strlen($actual_srv["code"])) {
$tpl = ffTemplate::factory(get_template_cascading("/", "google.analytics.html", "/services"));
$tpl->load_file("google.analytics.html", "main");
$tpl->set_var("code", $actual_srv["code"]);
$globals->fixed_post["body"][] = $tpl->rpparse("main", false);
}
I valori vivono in cm_mod_security_domains_fields — (field, group, value) con group = nome del servizio — e ci scrivono sia l'area Servizi del backend sia il wizard di installazione. Li carica get_webservices() / process_webservices() (library/gallery/common/get_webservices.php).
I servizi disponibili
| Categoria | Servizi |
|---|---|
| Analytics | analytics.google, google.tagmanager, analytics.clarity, analytics.contentsquare, webmaster.google |
| Marketing | linkedin.pixel, mailchimp, share.addthis, notification.optinmonster |
| Mappe e dati | google.maps, google.docs.auth, directory, place |
| Font e icone | font.google, font.google2, font.typekit, fontawesome |
| Meta e PWA | meta.favicon, meta.themecolor, meta.viewport |
| Notifiche | notification.onesignal, sms.joesmtp, sms.twilio (06) |
| Pagamenti | payment.stripe (§2, solo credenziali: non inietta niente) |
| Performance | lazyload, modernizr, debounce |
| Contenuti/strumenti | admin.tools, company.data, courtesy.page, img.aviary, facebook |
| Privacy | cookie.consent |
Aggiungere un servizio
conf/gallery/services/<nome>/config/index.phpcon i campi;conf/gallery/services/<nome>/index.phpcon l'iniezione;- il template del tag in
themes/<tema>/services/<nome>.html; - se è un tracker: dichiarare la categoria di consenso (§4).
4. Consenso cookie: gating vero, lato server
Il banner è il servizio cookie.consent (cookie jc_consent). La parte che conta è però server-side: prima di iniettare un servizio, process_webservices() chiama jc_consent_blocks($service_name) (in hook.php) e blocca la categoria non consentita.
jc_consent_category($service_name) // a quale categoria appartiene il servizio
jc_consent_active() // il banner è attivo?
jc_consent_granted($categoria) // l'utente ha acconsentito?
jc_consent_blocks($service_name) // → true: il tag NON viene iniettato
Due proprietà volute:
- È un blocco reale: il tag non arriva proprio nella pagina, non è nascosto lato client.
- È opt-in: se il banner non è attivo, nulla viene bloccato. I siti esistenti non cambiano comportamento quando si aggiorna il CMS.
Il banner è themes/gallery/contents/services/cookie.consent.html, reso da conf/gallery/services/cookie.consent/index.php. I testi sono codici del dizionario (svc_cookie_*, nelle quattro lingue); il link all'informativa, se nelle opzioni del servizio non se n'è messo uno, è /privacy nella lingua della pagina (content_i18n_url()). Fino alla 3.0.3 erano in italiano fisso, e il CSS in linea perdeva tre regole: {margin-left:auto}, {flex:1} e {text-decoration:underline} sono graffe con una sola coppia parola:parola, che il motore dei template scambia per variabili e cancella. Le regole che seguivano si fondevano con il selettore rimasto senza blocco, e il pannello «Personalizza» restava sempre aperto. Nel CSS di un template ogni regola chiude l'ultima dichiarazione con ;.
5. Altre librerie disponibili
library/ contiene dipendenze pronte all'uso, di qualità e attualità molto diverse. Le utili:
| Libreria | Uso |
|---|---|
phpmailer | invio SMTP: PHPMailer 7.1.1, con gli adattatori della 5.2 (06 §2) |
sentry | error tracking (13) |
html2pdf, PHPexcel | generazione PDF ed Excel |
mobiledetect, browser | rilevamento dispositivo |
minify, gminify, cssmin, jsmin | pipeline degli asset |
imap, vcard | posta in ingresso, contatti |
BunnyCDN | CDN |
algoliasearch-client | ricerca esterna |
SEOstats | metriche SEO (datata) |
rabbitMQ | broker di code, non cablato (05 §4) |
facebook-php-sdk, mailchimp, PayPal, OAuth2 | integrazioni |
E in vendor/: phpformsframework, wolfgan (Cms, auth, mailer, storage, cache, filemanager), hcore (anagraph, api, notifier, stats, jobs, logs, util), smarty, ckeditor, google-api-php-client, twilio, mongodb, symfony.
⚠️ Molte di queste librerie sono ferme a versioni vecchie e sono state toccate dalla migrazione a PHP 8. Prima di usarne una in un percorso critico, verificarla:
MIGRAZIONE_PHP7_PHP8.mdracconta anche i danni che un vecchioseddi massa aveva lasciato inPHPExcel,TCPDFeSEOstats.