Cache et performances
Le CMS a quatre caches distincts, avec des interrupteurs différents. Les confondre est la cause la plus fréquente du « j'ai modifié et rien ne change » et de son jumeau, « l'utilisateur voit la page d'un autre ».
1. Les quatre caches
| Cache | Ce qu'il mémorise | Comment on le pilote |
|---|---|---|
| de page | le HTML complet d'une URL | use_cache(false) dans le fichier ; $schema["page"][...]["cache"] dans le thème |
| des ressources | CSS/JS concaténés et minifiés, images redimensionnées | DEBUG_MODE, DISABLE_CACHE, CACHE_LAST_VERSION |
| des réglages | routage et configurations en mémoire | CM_ENABLE_MEM_CACHING (aujourd'hui false), __CLEARCACHE__ dans l'URL |
| applicatif | ce que vous y mettez | ffCache (vendor/phpformsframework/ffCache/) : sans adaptateur il dure une requête (§4) |
2. Cache de page
Le désactiver pour une page ou un service
use_cache(false); // library/gallery/common.php:369
Obligatoire en tête de :
- chaque page dynamique (contenu qui dépend de l'utilisateur, de la session, de l'heure) ;
- tous les services
/srvet les endpoints API — sans lui, le CMS peut servir une réponse périmée à un appel authentifié.
Les POST ne passent jamais par le cache de page, ni en lecture ni en écriture : check_static_cache_page() (library/gallery/system/cache.php) les écarte en premier et définit DISABLE_CACHE. La clé d'un fichier en cache contient les paramètres de la requête (index_email-…_XHR.gz), donc jusqu'à la 3.1.2 la réponse à un envoi était enregistrée puis renvoyée à quiconque renvoyait les mêmes champs, même si elle était fausse. Les GET, XHR compris, sont toujours enregistrés comme avant.
Ce qui sort dans la réponse
use_cache(false) éteint le cache du CMS (pas de fichier, pas de copie réutilisée par le CMS) : il faut le dire aussi au navigateur et aux caches intermédiaires, sinon ils gardent eux-mêmes la page pendant quelques secondes.
- page personnelle (quelqu'un connecté avec son compte, ou
use_cache(false)) : la réponse sort avecCache-Control: no-store, no-cache, must-revalidate, sansExpiresniLast-Modified(library/gallery/system/set_cache_page.php,library/gallery/system/cache.php) ; - page publique vue par un invité : elle reste
public— c'est voulu, pendant quelques secondes le navigateur ne la redemande pas. Lemax-agevaut3sur la réponse qui compose la page, etCM_PAGECACHE_GUEST_MAXAGE(par défaut7,cm/conf/config.php) quand elle arrive du cache de page (cache_parse()danslibrary/gallery/system/cache.php). Un site dont les contenus ne changent pas d'une minute à l'autre l'augmente dans la config d'environnement (config.remote.php), sans toucher au code.
Le défaut qui a rendu cette ligne nécessaire : les pages de l'espace sortaient quand même avec public, max-age=3, et pendant trois secondes le navigateur réutilisait la copie qu'il venait de voir — après la déconnexion on revoyait l'espace, et un cache partagé aurait pu le servir à une autre personne.
Ce que le PHP ne déclare pas, c'est Apache qui le décide. Le .htaccess du site (écrit par l'installeur, jc_htaccess_static_tail() dans install/lib.php) a mod_expires avec ExpiresByType text/html "access plus 0 seconds" : un contrôleur de module, un script sur mesure ou une redirection faite avec header('Location: …') sans en-têtes de cache ne restent pas dans le navigateur. Jusqu'à la 3.1.0 la ligne était "access plus 1 week", et Apache ajoutait max-age=604800 même à côté de celui du PHP : la redirection d'un module vers la connexion restait une semaine dans le navigateur et, après l'accès, le navigateur renvoyait tout seul à la connexion sans rien demander au site (JoeDesk, 2026-10-22). Le déploiement n'envoie jamais le .htaccess (bin/deploy.sh, 14) : sur un site installé avant, la ligne se change à la main. Un module, dans tous les cas, déclare le cache de ses réponses — no-store pour tout ce qui dépend de qui s'est connecté, redirections comprises.
Déclarer son niveau
Dans themes/<thème>/settings.php :
$schema["page"]["/"] = array("name" => "public", "cache" => "guest");
Valeurs admises (documentées dans library/gallery/settings.php) : user, group, guest, true, false, ou un chemin commençant par /.
guest— une seule copie, servie aux utilisateurs anonymes ; les connectés la sautent ;user— une copie par utilisateur ;group— une copie par groupe ;false— jamais en cache.
Dans le même fichier, $schema["request"]["/chemin"]["nocache"] désactive le cache par requête (true toujours, un tableau seulement si l'un de ces paramètres est dans la query) : c'est la voie pour les réponses qui dépendent de l'utilisateur et ne doivent pas finir dans un cache partagé, comme /OneSignalIdentity. Voir 01 §5.
Multilingue
Le cache est par langue : la langue est décidée par le préfixe de l'URL (/en/…), et de FF_LOCALE dépendent slugs, dictionnaire, templates et clé de cache. Pour changer de langue on change d'URL.
La persistance du choix (cookie lang, préférence sur le profil, redirection 302 vers l'URL préfixée) est en un seul endroit : language_pref_resolve() dans library/gallery/common/language_preference.php. Le kernel (vendor/wolfgan/cms/services/kernel.php) l'appelle juste après Auth::check() : la session est déjà là, il n'y a pas encore de sortie, et la page n'est pas encore passée par le cache, donc les pages non cachables le traversent aussi. cache_check_lang() dans library/gallery/system/cache.php reste comme entrée historique et renvoie au résolveur, qui ne tourne qu'une fois par requête.
Ordre de résolution, le premier qui répond l'emporte :
?lang=<CODE|tiny>— choix explicite : écrit le cookie et, si l'utilisateur est authentifié, le profil ; puis 302 vers l'URL de la langue choisie, sans?lang=. Le sélecteur[LANGUAGE_SWITCHER](library/gallery/process/language.php) lie toujours ainsi, même pour la langue par défaut : un lien direct vers/en/…changerait la page mais pas la langue dans laquelle l'utilisateur reçoit ses emails.- URL déjà préfixée — aligne seulement le cookie. Le profil n'est pas touché : ouvrir le lien de quelqu'un d'autre en anglais ne doit pas changer la langue des communications.
- URL canonique — profil (si authentifié) → cookie →
Accept-Language(seulement sur la racine/et seulement s'il n'y a pas encore de choix) → défaut. Une langue autre que celle par défaut mène à un 302.
Il ne tourne jamais en XHR, avec des méthodes autres que GET, sur un site avec une seule langue active, ni sur les chemins de service (/restricted, /admin, /api, /srv, /cronjob, /media, /static, ressources avec extension). Toujours 302, jamais 301 : un 301 resterait dans le cache du navigateur. Si la page n'existe pas dans la langue demandée, on reste où l'on est. Constantes facultatives, non définies par défaut : JC_LANG_COOKIE (nom du cookie) et JC_LANG_AUTODETECT (false désactive la détection par Accept-Language).
C'est un choix qui a été payé : deux implémentations de la même chose — une à l'init et une dans la couche cache — produisaient des URL corrompues. S'il faut toucher à la langue, on y touche dans le résolveur et seulement là.
Pour la langue des emails et des notifications voir 06 §2.
Canonical et sitemap par langue. Une page fichier dans une langue autre que celle par défaut déclare comme canonical sa propre adresse traduite (/en/contact, pas /contattaci) : set_header_page() (library/gallery/common/set_header_page.php) la tire de content_i18n_url(), à partir des slugs de contents/i18n.php. Les pages de vgallery ont leurs propres permaliens et ne passent pas par là. Le sitemap (modules/cms-common/models/Sitemap.php) liste chaque page fichier et la page d'accueil une fois par langue active, avec <xhtml:link rel="alternate" hreflang>, aux mêmes adresses que les canonical. Avec une seule langue, rien ne change. Détails et limites dans GUIDA_SITEMAP.md.
Compression et prévention de la double compression
JoeCMS prend en charge aussi bien la compression déléguée au serveur web (le standard sur les serveurs modernes avec mod_brotli ou mod_deflate, sur Cloudflare et sur les reverse proxies comme OpenResty), que la compression directe via PHP (gzencode()) pour les hébergements minimaux qui n'en disposent pas.
La fonction cm_can_compress() dans library/gallery/system/compression.php détecte automatiquement si le serveur web indique gérer la compression (via SERVER_COMPRESSION défini par .htaccess, les modules Apache mod_brotli/mod_deflate, le proxy OpenResty, les en-têtes Cloudflare ou zlib.output_compression dans php.ini) :
- Si le serveur gère la compression : PHP n'effectue aucune compression applicative, ne crée pas de copies
.gzinutiles sur le disque et sert du HTML brut avecreadfile(). Le serveur compresse une seule fois et le navigateur reçoit la page intacte. - Si le serveur ne compresse PAS et que le client supporte gzip : PHP compresse le HTML via gzip et le cache enregistre et sert le fichier pré-compressé pour maximiser les performances.
- Il est possible de forcer ce comportement avec la constante
CM_ENABLE_GZIP(falsepour désactiver la compression PHP en toute condition).
Invalider
refresh_cache($namespace, $node, $action, $path, $tags, $cats); // library/gallery/common/refresh_cache.php
refresh_cache_by_path($path);
update_vgallery l'appelle déjà quand on enregistre un contenu : encore une raison de ne pas réimplémenter l'enregistrement (07 §3).
Via le bus des services il y a aussi l'invalidation asynchrone : Jobs::async("/api/cache/refresh", array("url" => …)).
Et à la main, quand il faut le marteau : vider cache/. C'est ce que fait l'installeur à la fin de l'assistant, parce que les pages mises en cache pendant l'installation contiendraient des tokens pas encore résolus.
3. Cache des réglages et du routage
CM_ENABLE_MEM_CACHING vaut false dans conf/gallery/config.php, et peut être redéfinie depuis la config d'environnement. Cela signifie que le routeur relit les XML à chaque requête qui arrive jusqu'à lui (les pages servies par le cache de page n'y arrivent pas) :
- ✅ les modifications du routage sont immédiates, rien à vider ;
- ❌ on paie la lecture des XML, quelques millisecondes, sur les requêtes hors cache ;
- ⚠️
__CLEARCACHE__dans l'URL ne fonctionne que siCM_ENABLE_MEM_CACHINGest actif (cm/cm.php:255).
L'activer n'a de sens qu'avec un adaptateur qui conserve les données d'une requête à l'autre (§4) : sans FF_CACHE_ADAPTER la « mémoire » est ffGlobals et se perd à la fin de la requête, donc on n'économise rien ; avec apc ou fs sur PHP 8 le site plante dès la première requête. Avec redis ou memcached le chemin fonctionne (cmRouter::loadMem() et cmRouter::orderRules() dans cm/cmRouter.php), mais le gain reste de quelques millisecondes, sur les seules requêtes hors cache, et il exige la procédure de vidage dans le déploiement : en général, cela n'en vaut pas la peine.
4. ffCache : le cache applicatif
ffCache a des adaptateurs interchangeables, choisis avec FF_CACHE_ADAPTER dans la config d'environnement. Avec COMPOSER_PATH (les sites installés par l'assistant) c'est la copie de vendor/phpformsframework/ffCache/ qui tourne ; celle de ff/classes/ffCache/ ne sert que sans.
FF_CACHE_ADAPTER | Sur PHP 8 |
|---|---|
non défini (false, la valeur par défaut) | ffGlobals : les données durent le temps de la requête, puis se perdent |
apc | plante : apc.php étend ffCacheAdapterAdapter, une classe qui n'existe pas, et appelle apc_store()/apc_fetch(), qu'APCu sur PHP 8 n'a pas (seulement apcu_*) |
fs | plante : malgré son nom il n'écrit pas sur disque, c'est une copie de apc.php avec les mêmes apc_* |
memcached | extension memcached et un serveur Memcached |
redis | extension redis et un serveur Redis (FF_CACHE_REDIS_SERVER, FF_CACHE_REDIS_PORT) |
Plus vendor/wolfgan/cache/ avec les services page, sem (sémaphores) et shield.
Il est utilisé par le routeur (seulement avec CM_ENABLE_MEM_CACHING, §3), les templates et le traducteur du framework : sans adaptateur, pour eux tous c'est un cache de la seule requête. Installer APCu sur le serveur ne change rien, parce qu'aucun adaptateur ne l'appelle. Pour un cache applicatif du projet (résultats coûteux, réponses d'API externes, comptages) qui survive à la requête, sur un serveur avec APCu la voie qui fonctionne aujourd'hui est d'appeler directement apcu_fetch()/apcu_store(), précédés de function_exists() : le module est facultatif, et là où il manque, il n'y a tout simplement pas de cache.
5. Performances : quoi regarder, dans l'ordre
- La page est-elle en cache ? Une page publique qui fait
use_cache(false)« par sécurité » est la première cause de lenteur. Le bon niveau estguest, pas « pas de cache ». - Combien de requêtes fait-elle ? Le modèle vgallery est à champs dynamiques : une liste naïve fait une requête par nœud. On passe par les helpers (
get_vgallery_card,get_schema_fields_by_type) et on mesure. - Les images ont-elles un mode ? Servir l'original de 4 Mo là où il faut une miniature de 40 Ko est le gain le plus grand et le plus facile (11).
- Les ressources sont-elles minifiées et concaténées ?
DEBUG_MODEactivé en production les désactive. - Le travail lourd est-il synchrone ? Si oui, le déplacer vers une file ou un cron (05).
CM_ENABLE_MEM_CACHING: utile seulement avec un adaptateurredisoumemcached(§3, §4) ; sans, cela ne change rien.- Profiling :
conf/profiling/etlibrary/gallery/system/trace.phpcollectent les temps (13).
6. Symptômes et causes
| Symptôme | Cause |
|---|---|
| « J'ai modifié le template et rien ne change » | cache de page ; ou le bloc n'est pas parsé (02 §2) |
| Un endpoint JSON renvoie des données périmées | il manque use_cache(false) |
Un formulaire envoyé en ajax reçoit le HTML de la page d'accueil (<div id="L1" class="applets block">) au lieu du JSON du module | jusqu'à la 3.1.2 : POST XHR depuis une page qui a ses propres sections, intercepté par le raccourci XHR de library/gallery/system/init.php (01) puis enregistré en cache avec les champs du formulaire dans la clé. Depuis la 3.1.3 les POST ne prennent plus ce chemin et n'entrent pas en cache (§2) |
| Un utilisateur voit les données d'un autre | mauvais niveau de cache (guest/true sur une page personnelle) |
| La langue revient toujours à celle par défaut | intervention sur la langue hors de language_pref_resolve() |
Call to undefined function check_function() dans language_preference.php | le kernel appelle le résolveur avant library/gallery/common.php : cela arrive sur les zones réservées avec leur propre chemin (/gestione, pas /restricted), qui ne sont pas dans la liste des chemins ignorés. Le résolveur charge maintenant get_locale() lui-même (language_pref_has_locale()) |
| L'utilisateur change de langue mais les emails arrivent dans l'ancienne | lien direct vers /en/… au lieu de ?lang= : il change le cookie, pas le profil |
| Le CSS modifié n'arrive pas au navigateur | cache des ressources + Expires long : augmenter CACHE_LAST_VERSION |
| J'ai changé le routage et rien ne se passe | le XML modifié n'a pas été envoyé en production |
| L'image est l'ancienne version | cache des variantes dans cache/ |
Class "ffCacheAdapterAdapter" not found ou Call to undefined function apc_store() sur chaque page | FF_CACHE_ADAPTER réglé sur apc ou fs sur PHP 8 : on le retire de la config d'environnement (§4) |
| Après le déploiement les pages en cache ont encore des textes ou du code anciens, et les vider à nouveau règle le problème | opcache.revalidate_freq élevé sur le serveur : le cache a été vidé avant que PHP ne relise les fichiers (14 §4, « Le cache ») |
TypeError: sem_get(): Argument #1 ($key) must be of type int sur une page en cache | clé du sémaphore construite comme une chaîne : depuis PHP 8 c'est fatal même avec @. cache_sem_get_params() dans library/gallery/system/cache.php et getParams() dans vendor/wolfgan/cache/services/sem.php doivent toujours renvoyer un int sur 32 bits |
| La page affiche des caractères illisibles / hiéroglyphes binaires sans erreur PHP (HTTP 200) | double compression HTTP : le serveur web (Apache mod_deflate / OpenResty Brotli / Cloudflare) compressait une réponse déjà gzippée par PHP. Avec cm_can_compress() (library/gallery/system/compression.php), PHP détecte la compression en amont et sert du HTML brut en laissant le serveur compresser (§2) |