Cache e prestazioni
Il CMS ha quattro cache distinte, con interruttori diversi. Confonderle è la causa più comune del "ho modificato e non cambia niente" e del suo gemello, "l'utente vede la pagina di un altro".
1. Le quattro cache
| Cache | Cosa memorizza | Come si governa |
|---|---|---|
| di pagina | l'HTML completo di una URL | use_cache(false) nel file; $schema["page"][...]["cache"] nel tema |
| di asset | CSS/JS concatenati e minificati, immagini ridimensionate | DEBUG_MODE, DISABLE_CACHE, CACHE_LAST_VERSION |
| di settaggi | routing e configurazioni in memoria | CM_ENABLE_MEM_CACHING (oggi false), __CLEARCACHE__ in URL |
| applicativa | quello che ci metti tu | ffCache (vendor/phpformsframework/ffCache/): senza adapter dura una richiesta (§4) |
2. Cache di pagina
Disattivarla per una pagina o un servizio
use_cache(false); // library/gallery/common.php:369
Obbligatorio in cima a:
- ogni pagina dinamica (contenuto che dipende dall'utente, dalla sessione, dall'ora);
- tutti i servizi
/srve gli endpoint API — senza, il CMS può servire una risposta vecchia a una chiamata autenticata.
Le POST non passano mai dalla cache di pagina, né in lettura né in scrittura: check_static_cache_page() (library/gallery/system/cache.php) le scarta per prime e definisce DISABLE_CACHE. La chiave di un file in cache contiene i parametri della richiesta (index_email-…_XHR.gz), quindi fino alla 3.1.2 la risposta a un invio veniva salvata e poi restituita a chiunque rimandasse gli stessi campi, anche se era sbagliata. Le GET, XHR comprese, continuano a essere salvate come prima.
Cosa esce nella risposta
use_cache(false) spegne la cache del CMS (niente file, niente copia riusata dal CMS): va detto anche al browser e alle cache in mezzo, o per qualche secondo tengono loro la pagina.
- pagina personale (chi è entrato con il suo account, o
use_cache(false)): la risposta esceCache-Control: no-store, no-cache, must-revalidate, senzaExpiresnéLast-Modified(library/gallery/system/set_cache_page.php,library/gallery/system/cache.php); - pagina pubblica vista da un ospite: resta
public— è voluto, per qualche secondo il browser non la richiede. Ilmax-ageè3sulla risposta che compone la pagina, eCM_PAGECACHE_GUEST_MAXAGE(default7,cm/conf/config.php) quando arriva dalla cache di pagina (cache_parse()inlibrary/gallery/system/cache.php). Un sito con contenuti che non cambiano di minuto in minuto lo alza nel config d'ambiente (config.remote.php), senza toccare il codice.
Il difetto che ha reso necessaria questa riga: le pagine dell'area uscivano comunque public, max-age=3, e per tre secondi il browser riusava la copia appena vista — dopo l'uscita si rivedeva l'area, e una cache condivisa avrebbe potuto servirla a un'altra persona.
Quello che il PHP non dichiara lo decide Apache. Il .htaccess del sito (lo scrive l'installer, jc_htaccess_static_tail() in install/lib.php) ha mod_expires con ExpiresByType text/html "access plus 0 seconds": un controller di modulo, uno script su misura o un redirect fatto con header('Location: …') senza intestazioni di cache non restano nel browser. Fino alla 3.1.0 la riga era "access plus 1 week", e Apache aggiungeva max-age=604800 anche accanto a quello del PHP: il redirect di un modulo verso il login restava una settimana nel browser e, dopo l'accesso, il browser rimandava al login da solo senza chiedere niente al sito (JoeDesk, 2026-10-22). Il deploy non carica mai il .htaccess (bin/deploy.sh, 14): su un sito installato prima la riga va cambiata a mano. Un modulo, in ogni caso, dichiara la cache delle sue risposte — no-store per tutto ciò che dipende da chi è entrato, redirect compresi.
Dichiararne il livello
In themes/<tema>/settings.php:
$schema["page"]["/"] = array("name" => "public", "cache" => "guest");
Valori ammessi (documentati in library/gallery/settings.php): user, group, guest, true, false, oppure un percorso che inizia con /.
guest— una copia sola, servita agli utenti anonimi; chi è loggato la salta;user— una copia per utente;group— una copia per gruppo;false— mai in cache.
Nello stesso file, $schema["request"]["/percorso"]["nocache"] spegne la cache per singola richiesta (true sempre, un array solo se in query c'è uno di quei parametri): è la via per le risposte che dipendono dall'utente e non devono finire in una cache condivisa, come /OneSignalIdentity. Vedi 01 §5.
Multilingua
La cache è per lingua: la lingua la decide il prefisso dell'URL (/en/…), e da FF_LOCALE dipendono slug, dizionario, template e chiave di cache. Per cambiare lingua si cambia URL.
La persistenza della scelta (cookie lang, preferenza sul profilo, redirect 302 verso l'URL prefissato) sta in un solo punto: language_pref_resolve() in library/gallery/common/language_preference.php. La chiama il kernel (vendor/wolfgan/cms/services/kernel.php) subito dopo Auth::check(): c'è già la sessione, non c'è ancora output, e la pagina non è ancora passata dalla cache, quindi la attraversano anche le pagine non cacheabili. cache_check_lang() in library/gallery/system/cache.php resta come ingresso storico e rimanda al resolver, che gira una sola volta per richiesta.
Ordine di risoluzione, il primo che risponde vince:
?lang=<CODE|tiny>— scelta esplicita: scrive il cookie e, se l'utente è autenticato, il profilo; poi 302 sull'URL della lingua scelta, senza?lang=. Il selettore[LANGUAGE_SWITCHER](library/gallery/process/language.php) linka sempre così, anche per la lingua predefinita: un link diretto a/en/…cambierebbe la pagina ma non la lingua in cui l'utente riceve le email.- URL già prefissato — allinea il solo cookie. Il profilo non si tocca: aprire un link altrui in inglese non deve cambiare la lingua delle comunicazioni.
- URL canonico — profilo (se autenticato) → cookie →
Accept-Language(solo sulla radice/e solo se non c'è ancora una scelta) → default. Una lingua non predefinita porta a un 302.
Non gira mai su XHR, su metodi diversi da GET, su un sito con una sola lingua attiva, né sui percorsi di servizio (/restricted, /admin, /api, /srv, /cronjob, /media, /static, asset con estensione). Sempre 302, mai 301: un 301 resterebbe nella cache del browser. Se la pagina non esiste nella lingua richiesta si resta dove si è. Costanti facoltative, non definite di default: JC_LANG_COOKIE (nome del cookie) e JC_LANG_AUTODETECT (false spegne il rilevamento da Accept-Language).
È stata una scelta pagata: due implementazioni della stessa cosa — una all'init e una nel layer cache — producevano URL corrotti. Se serve toccare la lingua, si tocca nel resolver e solo lì.
Per la lingua di email e notifiche vedi 06 §2.
Canonical e sitemap per lingua. Una pagina a file in una lingua non predefinita dichiara come canonical il proprio indirizzo tradotto (/en/contact, non /contattaci): set_header_page() (library/gallery/common/set_header_page.php) lo ricava con content_i18n_url() dagli slug di contents/i18n.php. Le pagine di vgallery hanno permalink propri e non passano di lì. La sitemap (modules/cms-common/models/Sitemap.php) elenca ogni pagina a file e la home una volta per lingua attiva, con <xhtml:link rel="alternate" hreflang>, agli stessi indirizzi dei canonical. Con una lingua sola non cambia niente. Dettagli e limiti in GUIDA_SITEMAP.md.
Compressione e prevenzione della doppia compressione
JoeCMS supporta sia la compressione delegata al web server (la prassi sui server moderni con mod_brotli o mod_deflate, su Cloudflare e su reverse proxy come OpenResty), sia la compressione diretta via PHP (gzencode()) per gli hosting minimali che non la forniscono.
La funzione cm_can_compress() in library/gallery/system/compression.php rileva automaticamente se il web server segnala di gestire la compressione (tramite SERVER_COMPRESSION impostato da .htaccess, moduli Apache mod_brotli/mod_deflate, proxy OpenResty, header Cloudflare o zlib.output_compression in php.ini):
- Se il server gestisce la compressione: PHP non esegue compressione applicativa, non crea copie
.gzinutili su disco e serve HTML in chiaro conreadfile(). Il server comprime una sola volta e il browser riceve la pagina integra. - Se il server NON comprime e il client supporta gzip: PHP comprime l'HTML via gzip e la cache salva e serve il file pre-compresso per massimizzare le prestazioni.
- È possibile forzare il comportamento con la costante
CM_ENABLE_GZIP(falseper disattivare la compressione PHP in qualsiasi condizione).
Invalidare
refresh_cache($namespace, $node, $action, $path, $tags, $cats); // library/gallery/common/refresh_cache.php
refresh_cache_by_path($path);
update_vgallery la chiama già quando si salva un contenuto: è un altro motivo per non reimplementare il salvataggio (07 §3).
Via bus dei servizi c'è anche l'invalidazione asincrona: Jobs::async("/api/cache/refresh", array("url" => …)).
E a mano, quando serve il martello: svuotare cache/. È ciò che fa l'installer al termine del wizard, perché le pagine cachate durante l'installazione conterrebbero token non ancora risolti.
3. Cache di settaggi e routing
CM_ENABLE_MEM_CACHING è false in conf/gallery/config.php, sovrascrivibile dal config d'ambiente. Significa che il router rilegge gli XML a ogni richiesta che arriva fino a lui (le pagine servite dalla cache di pagina non ci arrivano):
- ✅ le modifiche al routing sono immediate, niente da svuotare;
- ❌ si paga la lettura degli XML, pochi millisecondi, sulle richieste fuori cache;
- ⚠️
__CLEARCACHE__in URL funziona solo seCM_ENABLE_MEM_CACHINGè attivo (cm/cm.php:255).
Accenderla ha senso solo con un adapter che conserva i dati fra una richiesta e l'altra (§4): senza FF_CACHE_ADAPTER la «memoria» è ffGlobals e si perde a fine richiesta, quindi non si risparmia niente; con apc o fs su PHP 8 il sito va in errore alla prima richiesta. Con redis o memcached il percorso funziona (cmRouter::loadMem() e cmRouter::orderRules() in cm/cmRouter.php), ma il guadagno resta di pochi millisecondi sulle sole richieste fuori cache, e chiede la procedura di svuotamento nel deploy: di solito non vale la pena.
4. ffCache: la cache applicativa
ffCache ha adapter intercambiabili, scelti con FF_CACHE_ADAPTER nel config d'ambiente. Con COMPOSER_PATH (i siti installati dal wizard) gira la copia in vendor/phpformsframework/ffCache/; quella in ff/classes/ffCache/ serve solo senza.
FF_CACHE_ADAPTER | Su PHP 8 |
|---|---|
non definito (false, il default) | ffGlobals: i dati durano quanto la richiesta, poi si perdono |
apc | va in errore: apc.php estende ffCacheAdapterAdapter, una classe che non esiste, e chiama apc_store()/apc_fetch(), che APCu su PHP 8 non ha (solo apcu_*) |
fs | va in errore: nonostante il nome non scrive su disco, è una copia di apc.php con le stesse apc_* |
memcached | estensione memcached e un server Memcached |
redis | estensione redis e un server Redis (FF_CACHE_REDIS_SERVER, FF_CACHE_REDIS_PORT) |
Più vendor/wolfgan/cache/ con i servizi page, sem (semafori) e shield.
La usano il router (solo con CM_ENABLE_MEM_CACHING, §3), i template e il traduttore del framework: senza adapter, per tutti loro è una cache della singola richiesta. Installare APCu sul server non cambia niente, perché nessun adapter lo chiama. Per una cache applicativa di progetto (risultati costosi, risposte di API esterne, conteggi) che sopravviva alla richiesta, su un server con APCu la via che funziona oggi è chiamare apcu_fetch()/apcu_store() direttamente, con function_exists() davanti: il modulo è facoltativo, e dove manca la cache semplicemente non c'è.
5. Prestazioni: cosa guardare, in ordine
- La pagina è in cache? Una pagina pubblica che fa
use_cache(false)"per sicurezza" è la prima causa di lentezza. Il livello giusto èguest, non "niente cache". - Quante query fa? Il modello vgallery è a campi dinamici: un elenco ingenuo fa una query per nodo. Si passa dagli helper (
get_vgallery_card,get_schema_fields_by_type) e si misura. - Le immagini hanno un modo? Servire l'originale da 4 MB dove serve una miniatura da 40 KB è il guadagno più grande e più facile (11).
- Gli asset sono minificati e concatenati?
DEBUG_MODEacceso in produzione li disattiva. - Il lavoro pesante è sincrono? Se sì, spostarlo su coda o cron (05).
CM_ENABLE_MEM_CACHING: utile solo con un adapterredisomemcached(§3, §4); senza, non cambia niente.- Profiling:
conf/profiling/elibrary/gallery/system/trace.phpraccolgono i tempi (13).
6. Sintomi e cause
| Sintomo | Causa |
|---|---|
| "Ho modificato il template e non cambia niente" | cache di pagina; oppure il blocco non è parsato (02 §2) |
| Un endpoint JSON restituisce dati vecchi | manca use_cache(false) |
Un form inviato via ajax riceve l'HTML della home (<div id="L1" class="applets block">) invece del JSON del modulo | fino alla 3.1.2: XHR in POST da una pagina con sezioni, intercettata dalla scorciatoia XHR di library/gallery/system/init.php (01) e poi salvata in cache con i campi del form nella chiave. Dalla 3.1.3 le POST non prendono più quella strada e non entrano in cache (§2) |
| Un utente vede i dati di un altro | livello di cache sbagliato (guest/true su una pagina personale) |
| La lingua torna sempre a quella di default | intervento sulla lingua fuori da language_pref_resolve() |
Call to undefined function check_function() in language_preference.php | il kernel chiama il resolver prima di library/gallery/common.php: succede sulle aree riservate con un percorso proprio (/gestione, non /restricted), che non stanno nell'elenco dei percorsi saltati. Il resolver ora carica get_locale() da sé (language_pref_has_locale()) |
| L'utente cambia lingua ma le email arrivano nella vecchia | link diretto a /en/… invece di ?lang=: cambia il cookie, non il profilo |
| Il CSS modificato non arriva al browser | cache asset + Expires lungo: bumpare CACHE_LAST_VERSION |
| Ho cambiato il routing e non succede nulla | l'XML modificato non è stato caricato in produzione |
| L'immagine è la versione vecchia | cache delle varianti in cache/ |
Class "ffCacheAdapterAdapter" not found o Call to undefined function apc_store() su ogni pagina | FF_CACHE_ADAPTER impostato a apc o fs su PHP 8: si toglie dal config d'ambiente (§4) |
| Dopo il deploy le pagine in cache hanno ancora testi o codice vecchi, e svuotarle di nuovo le sistema | opcache.revalidate_freq alto sul server: la cache è stata svuotata prima che PHP rileggesse i file (14 §4, «La cache») |
TypeError: sem_get(): Argument #1 ($key) must be of type int su una pagina in cache | chiave del semaforo costruita come stringa: da PHP 8 è fatal anche con @. cache_sem_get_params() in library/gallery/system/cache.php e getParams() in vendor/wolfgan/cache/services/sem.php devono restituire sempre un int a 32 bit |
| La pagina mostra caratteri illeggibili / geroglifici binari senza errori PHP (HTTP 200) | doppia compressione HTTP: il web server (Apache mod_deflate / OpenResty Brotli / Cloudflare) comprimeva una risposta già gzippata da PHP. Con cm_can_compress() (library/gallery/system/compression.php), PHP rileva la compressione a monte e serve HTML in chiaro lasciando comprimere al server (§2) |