Vai al contenuto
JoeCMS Scarica 3.1.5
Manuale · 10

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:

ModuloContenuto
authlogin, registrazione, recupero, attivazione, social (08)
restrictedil backend: ^/restricted(.*) → /layout$0, ^/admin/settings(.*) → /settings$1
cms-commonil modulo di progetto: la regola /srv/(.*) → /applets/services/$1 e models/Sitemap.php
securitycontenuti del modulo di sicurezza
package-managergestione 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 di Auth::addEvent(), un helper) c'è hook.local.php, accanto a hook.php: lo include hook.php in 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:

  1. Validazione di sicurezza: verifica del file ZIP con blocco dei percorsi pericolosi (path traversal ../ o assoluti).
  2. Lettura del descrittore manifest.json: metadati del modulo, versione minima di JoeCMS richiesta, dipendenze.
  3. Estrazione selettiva: scompatta i componenti nelle rispettive cartelle (modules/<id>/, contents/, themes/).
  4. Auto-aggiornamento del database: se il manifest specifica database.schema, esegue automaticamente la DDL SQL tramite la connessione attiva.
  5. 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:

PrefissoFile 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:

ModuloCosa fa
formcostruttore di form: definizione dei campi da backend, selezioni, listini, invio email con template, revisioni, archivio delle compilazioni (manage/, detail.php)
searchricerca sui contenuti, con configurazione, gruppi, extra e anteprima
newsletteriscrizioni e invii
calendareventi a calendario
mapsmappe
sharecondivisione social
tagcloudnuvola di tag
videobar, fbalbum, swfmedia e gallerie (componenti datati)
registerregistrazione
shippingpricecosti 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 chiama verify(), 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 (pubblicabile pk_…), api_key (segreta sk_…), 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 costanti STRIPE_PUBLIC, STRIPE_SECRET, STRIPE_WEBHOOK_SECRET, STRIPE_CURRENCY.
  • L'ambiente lo dice la chiave: solo sk_live_ / rk_live_ incassano soldi veri (ambiente() risponde live, test o ignoto). Se ci si dimentica di cambiare chiave si resta in prova.
  • Le date passano dal fuso del sito: Payment::fuso() usa TIMEZONE (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

CategoriaServizi
Analyticsanalytics.google, google.tagmanager, analytics.clarity, analytics.contentsquare, webmaster.google
Marketinglinkedin.pixel, mailchimp, share.addthis, notification.optinmonster
Mappe e datigoogle.maps, google.docs.auth, directory, place
Font e iconefont.google, font.google2, font.typekit, fontawesome
Meta e PWAmeta.favicon, meta.themecolor, meta.viewport
Notifichenotification.onesignal, sms.joesmtp, sms.twilio (06)
Pagamentipayment.stripe (§2, solo credenziali: non inietta niente)
Performancelazyload, modernizr, debounce
Contenuti/strumentiadmin.tools, company.data, courtesy.page, img.aviary, facebook
Privacycookie.consent

Aggiungere un servizio

  1. conf/gallery/services/<nome>/config/index.php con i campi;
  2. conf/gallery/services/<nome>/index.php con l'iniezione;
  3. il template del tag in themes/<tema>/services/<nome>.html;
  4. se è un tracker: dichiarare la categoria di consenso (§4).

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:

LibreriaUso
phpmailerinvio SMTP: PHPMailer 7.1.1, con gli adattatori della 5.2 (06 §2)
sentryerror tracking (13)
html2pdf, PHPexcelgenerazione PDF ed Excel
mobiledetect, browserrilevamento dispositivo
minify, gminify, cssmin, jsminpipeline degli asset
imap, vcardposta in ingresso, contatti
BunnyCDNCDN
algoliasearch-clientricerca esterna
SEOstatsmetriche SEO (datata)
rabbitMQbroker di code, non cablato (05 §4)
facebook-php-sdk, mailchimp, PayPal, OAuth2integrazioni

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.md racconta anche i danni che un vecchio sed di massa aveva lasciato in PHPExcel, TCPDF e SEOstats.