Vai al contenuto
JoeCMS Scarica 3.1.5
Manuale · 12

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

CacheCosa memorizzaCome si governa
di paginal'HTML completo di una URLuse_cache(false) nel file; $schema["page"][...]["cache"] nel tema
di assetCSS/JS concatenati e minificati, immagini ridimensionateDEBUG_MODE, DISABLE_CACHE, CACHE_LAST_VERSION
di settaggirouting e configurazioni in memoriaCM_ENABLE_MEM_CACHING (oggi false), __CLEARCACHE__ in URL
applicativaquello che ci metti tuffCache (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 /srv e 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 esce Cache-Control: no-store, no-cache, must-revalidate, senza Expires né 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. Il max-age è 3 sulla risposta che compone la pagina, e CM_PAGECACHE_GUEST_MAXAGE (default 7, cm/conf/config.php) quando arriva dalla cache di pagina (cache_parse() in library/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:

  1. ?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.
  2. 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.
  3. 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 .gz inutili su disco e serve HTML in chiaro con readfile(). 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 (false per 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 se CM_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_ADAPTERSu PHP 8
non definito (false, il default)ffGlobals: i dati durano quanto la richiesta, poi si perdono
apcva 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_*)
fsva in errore: nonostante il nome non scrive su disco, è una copia di apc.php con le stesse apc_*
memcachedestensione memcached e un server Memcached
redisestensione 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

  1. 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".
  2. 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.
  3. 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).
  4. Gli asset sono minificati e concatenati? DEBUG_MODE acceso in produzione li disattiva.
  5. Il lavoro pesante è sincrono? Se sì, spostarlo su coda o cron (05).
  6. CM_ENABLE_MEM_CACHING: utile solo con un adapter redis o memcached (§3, §4); senza, non cambia niente.
  7. Profiling: conf/profiling/ e library/gallery/system/trace.php raccolgono i tempi (13).

6. Sintomi e cause

SintomoCausa
"Ho modificato il template e non cambia niente"cache di pagina; oppure il blocco non è parsato (02 §2)
Un endpoint JSON restituisce dati vecchimanca use_cache(false)
Un form inviato via ajax riceve l'HTML della home (<div id="L1" class="applets block">) invece del JSON del modulofino 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 altrolivello di cache sbagliato (guest/true su una pagina personale)
La lingua torna sempre a quella di defaultintervento sulla lingua fuori da language_pref_resolve()
Call to undefined function check_function() in language_preference.phpil 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 vecchialink diretto a /en/… invece di ?lang=: cambia il cookie, non il profilo
Il CSS modificato non arriva al browsercache asset + Expires lungo: bumpare CACHE_LAST_VERSION
Ho cambiato il routing e non succede nullal'XML modificato non è stato caricato in produzione
L'immagine è la versione vecchiacache delle varianti in cache/
Class "ffCacheAdapterAdapter" not found o Call to undefined function apc_store() su ogni paginaFF_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 sistemaopcache.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 cachechiave 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)