Cache and performance
The CMS has four distinct caches, with different switches. Mixing them up is the most common cause of "I changed it and nothing changes" and its twin, "the user sees someone else's page".
1. The four caches
| Cache | What it stores | How it's controlled |
|---|---|---|
| page | the full HTML of a URL | use_cache(false) in the file; $schema["page"][...]["cache"] in the theme |
| asset | concatenated and minified CSS/JS, resized images | DEBUG_MODE, DISABLE_CACHE, CACHE_LAST_VERSION |
| settings | routing and configurations in memory | CM_ENABLE_MEM_CACHING (currently false), __CLEARCACHE__ in the URL |
| application | whatever you put in it | ffCache (vendor/phpformsframework/ffCache/): without an adapter it lasts one request (§4) |
2. Page cache
Turning it off for a page or a service
use_cache(false); // library/gallery/common.php:369
Mandatory at the top of:
- every dynamic page (content depending on the user, the session, the time);
- all
/srvservices and API endpoints — without it, the CMS may serve a stale response to an authenticated call.
POST requests never go through the page cache, neither for reading nor for writing: check_static_cache_page() (library/gallery/system/cache.php) discards them first and defines DISABLE_CACHE. The key of a cached file contains the request parameters (index_email-…_XHR.gz), so up to 3.1.2 the response to a submission was saved and then returned to anyone who sent the same fields again, even when it was wrong. GETs, XHR included, are still saved as before.
What goes out in the response
use_cache(false) turns off the CMS cache (no file, no copy reused by the CMS): the browser and the caches in between must be told too, or for a few seconds they keep the page themselves.
- personal page (someone signed in with their account, or
use_cache(false)): the response goes out withCache-Control: no-store, no-cache, must-revalidate, withoutExpiresorLast-Modified(library/gallery/system/set_cache_page.php,library/gallery/system/cache.php); - public page seen by a guest: it stays
public— on purpose, for a few seconds the browser doesn't request it again. Themax-ageis3on the response that composes the page, andCM_PAGECACHE_GUEST_MAXAGE(default7,cm/conf/config.php) when it comes from the page cache (cache_parse()inlibrary/gallery/system/cache.php). A site whose content doesn't change from one minute to the next raises it in the environment config (config.remote.php), without touching the code.
The defect that made this line necessary: the area's pages went out with public, max-age=3 anyway, and for three seconds the browser reused the copy it had just seen — after signing out you saw the area again, and a shared cache could have served it to another person.
What PHP doesn't declare, Apache decides. The site's .htaccess (written by the installer, jc_htaccess_static_tail() in install/lib.php) has mod_expires with ExpiresByType text/html "access plus 0 seconds": a module controller, a custom script or a redirect done with header('Location: …') without cache headers don't stay in the browser. Up to 3.1.0 the line was "access plus 1 week", and Apache added max-age=604800 even next to the PHP one: a module's redirect to the login stayed a week in the browser and, after signing in, the browser sent you back to the login by itself without asking the site anything (JoeDesk, 2026-10-22). The deploy never uploads the .htaccess (bin/deploy.sh, 14): on a site installed before, the line must be changed by hand. A module, in any case, declares the cache of its responses — no-store for everything that depends on who signed in, redirects included.
Declaring its level
In themes/<theme>/settings.php:
$schema["page"]["/"] = array("name" => "public", "cache" => "guest");
Allowed values (documented in library/gallery/settings.php): user, group, guest, true, false, or a path starting with /.
guest— a single copy, served to anonymous users; logged-in users skip it;user— one copy per user;group— one copy per group;false— never cached.
In the same file, $schema["request"]["/path"]["nocache"] turns off caching per request (true always, an array only if one of those parameters is in the query): it's the way for responses that depend on the user and must not end up in a shared cache, like /OneSignalIdentity. See 01 §5.
Multilingual
The cache is per language: the language is decided by the URL prefix (/en/…), and slugs, dictionary, templates and cache key depend on FF_LOCALE. To change language you change URL.
Persisting the choice (lang cookie, profile preference, 302 redirect to the prefixed URL) lives in a single place: language_pref_resolve() in library/gallery/common/language_preference.php. The kernel (vendor/wolfgan/cms/services/kernel.php) calls it right after Auth::check(): the session is already there, there's no output yet, and the page hasn't gone through the cache yet, so non-cacheable pages pass through it too. cache_check_lang() in library/gallery/system/cache.php stays as the historical entry and defers to the resolver, which runs only once per request.
Resolution order, the first that answers wins:
?lang=<CODE|tiny>— explicit choice: writes the cookie and, if the user is authenticated, the profile; then a 302 to the URL of the chosen language, without?lang=. The[LANGUAGE_SWITCHER](library/gallery/process/language.php) always links like this, even for the default language: a direct link to/en/…would change the page but not the language the user receives emails in.- Already-prefixed URL — aligns only the cookie. The profile isn't touched: opening someone else's link in English must not change the language of communications.
- Canonical URL — profile (if authenticated) → cookie →
Accept-Language(only on the root/and only if there's no choice yet) → default. A non-default language leads to a 302.
It never runs on XHR, on methods other than GET, on a site with a single active language, or on service paths (/restricted, /admin, /api, /srv, /cronjob, /media, /static, assets with an extension). Always 302, never 301: a 301 would stay in the browser cache. If the page doesn't exist in the requested language, you stay where you are. Optional constants, not defined by default: JC_LANG_COOKIE (cookie name) and JC_LANG_AUTODETECT (false turns off detection from Accept-Language).
It was a choice paid for: two implementations of the same thing — one at init and one in the cache layer — produced corrupted URLs. If you need to touch the language, touch it in the resolver and only there.
For the language of emails and notifications see 06 §2.
Canonical and sitemap per language. A file page in a non-default language declares its own translated address as canonical (/en/contact, not /contattaci): set_header_page() (library/gallery/common/set_header_page.php) derives it with content_i18n_url() from the slugs in contents/i18n.php. vgallery pages have their own permalinks and don't go through there. The sitemap (modules/cms-common/models/Sitemap.php) lists every file page and the home page once per active language, with <xhtml:link rel="alternate" hreflang>, at the same addresses as the canonicals. With a single language nothing changes. Details and limits in GUIDA_SITEMAP.md.
Compression and double compression prevention
JoeCMS supports both compression delegated to the web server (standard on modern servers with mod_brotli or mod_deflate, on Cloudflare, and on reverse proxies like OpenResty), as well as direct compression via PHP (gzencode()) for minimal hostings that do not provide it.
The cm_can_compress() function in library/gallery/system/compression.php automatically detects whether the web server signals that it handles compression (via SERVER_COMPRESSION set by .htaccess, Apache modules mod_brotli/mod_deflate, OpenResty proxy, Cloudflare headers, or zlib.output_compression in php.ini):
- If the server handles compression: PHP does not perform application compression, avoids creating unnecessary
.gzcopies on disk, and serves plain HTML usingreadfile(). The server compresses once, and the browser receives intact content. - If the server does NOT compress and the client supports gzip: PHP compresses HTML via gzip, and the cache saves and serves the pre-compressed file to maximize performance.
- The behavior can be forced via the
CM_ENABLE_GZIPconstant (falseto disable PHP compression under any condition).
Invalidating
refresh_cache($namespace, $node, $action, $path, $tags, $cats); // library/gallery/common/refresh_cache.php
refresh_cache_by_path($path);
update_vgallery already calls it when content is saved: another reason not to reimplement saving (07 §3).
Via the service bus there's also asynchronous invalidation: Jobs::async("/api/cache/refresh", array("url" => …)).
And by hand, when you need the hammer: empty cache/. It's what the installer does at the end of the wizard, because pages cached during installation would contain tokens not yet resolved.
3. Settings and routing cache
CM_ENABLE_MEM_CACHING is false in conf/gallery/config.php, and can be overridden from the environment config. It means the router rereads the XML on every request that reaches it (pages served from the page cache don't get that far):
- ✅ routing changes are immediate, nothing to empty;
- ❌ you pay for reading the XML, a few milliseconds, on requests outside the cache;
- ⚠️
__CLEARCACHE__in the URL works only ifCM_ENABLE_MEM_CACHINGis on (cm/cm.php:255).
Turning it on only makes sense with an adapter that keeps data from one request to the next (§4): without FF_CACHE_ADAPTER the "memory" is ffGlobals and is lost at the end of the request, so nothing is saved; with apc or fs on PHP 8 the site errors out on the first request. With redis or memcached the path works (cmRouter::loadMem() and cmRouter::orderRules() in cm/cmRouter.php), but the gain is still a few milliseconds, on requests outside the cache only, and it calls for the emptying procedure in the deploy: usually it isn't worth it.
4. ffCache: the application cache
ffCache has interchangeable adapters, chosen with FF_CACHE_ADAPTER in the environment config. With COMPOSER_PATH (sites installed by the wizard) the copy in vendor/phpformsframework/ffCache/ runs; the one in ff/classes/ffCache/ is only used without it.
FF_CACHE_ADAPTER | On PHP 8 |
|---|---|
not defined (false, the default) | ffGlobals: data lasts as long as the request, then it's lost |
apc | errors out: apc.php extends ffCacheAdapterAdapter, a class that doesn't exist, and calls apc_store()/apc_fetch(), which APCu on PHP 8 doesn't have (only apcu_*) |
fs | errors out: despite the name it doesn't write to disk, it's a copy of apc.php with the same apc_* |
memcached | memcached extension and a Memcached server |
redis | redis extension and a Redis server (FF_CACHE_REDIS_SERVER, FF_CACHE_REDIS_PORT) |
Plus vendor/wolfgan/cache/ with the page, sem (semaphores) and shield services.
It's used by the router (only with CM_ENABLE_MEM_CACHING, §3), the templates and the framework's translator: without an adapter, for all of them it's a single-request cache. Installing APCu on the server changes nothing, because no adapter calls it. For a project application cache (expensive results, external API responses, counts) that outlives the request, on a server with APCu the way that works today is to call apcu_fetch()/apcu_store() directly, with function_exists() in front: the module is optional, and where it's missing there simply is no cache.
5. Performance: what to look at, in order
- Is the page cached? A public page doing
use_cache(false)"to be safe" is the first cause of slowness. The right level isguest, not "no cache". - How many queries does it run? The vgallery model has dynamic fields: a naive list runs one query per node. Go through the helpers (
get_vgallery_card,get_schema_fields_by_type) and measure. - Do images have a mode? Serving the 4 MB original where a 40 KB thumbnail is needed is the biggest and easiest win (11).
- Are assets minified and concatenated?
DEBUG_MODEon in production turns that off. - Is heavy work synchronous? If so, move it to a queue or cron (05).
CM_ENABLE_MEM_CACHING: useful only with aredisormemcachedadapter (§3, §4); without one, it changes nothing.- Profiling:
conf/profiling/andlibrary/gallery/system/trace.phpcollect timings (13).
6. Symptoms and causes
| Symptom | Cause |
|---|---|
| "I changed the template and nothing changes" | page cache; or the block isn't parsed (02 §2) |
| A JSON endpoint returns stale data | use_cache(false) is missing |
A form sent via ajax receives the home page HTML (<div id="L1" class="applets block">) instead of the module's JSON | up to 3.1.2: XHR POST from a page with its own sections, caught by the XHR shortcut in library/gallery/system/init.php (01) and then saved in the cache with the form fields in the key. Since 3.1.3 POSTs no longer take that path and do not enter the cache (§2) |
| A user sees someone else's data | wrong cache level (guest/true on a personal page) |
| The language keeps going back to the default | language handling outside language_pref_resolve() |
Call to undefined function check_function() in language_preference.php | the kernel calls the resolver before library/gallery/common.php: it happens on reserved areas with their own path (/gestione, not /restricted), which aren't in the list of skipped paths. The resolver now loads get_locale() itself (language_pref_has_locale()) |
| The user changes language but emails arrive in the old one | direct link to /en/… instead of ?lang=: it changes the cookie, not the profile |
| Modified CSS doesn't reach the browser | asset cache + long Expires: bump CACHE_LAST_VERSION |
| I changed routing and nothing happens | the modified XML wasn't uploaded to production |
| The image is the old version | variant cache in cache/ |
Class "ffCacheAdapterAdapter" not found or Call to undefined function apc_store() on every page | FF_CACHE_ADAPTER set to apc or fs on PHP 8: remove it from the environment config (§4) |
| After the deploy the cached pages still have old text or code, and emptying them again fixes it | high opcache.revalidate_freq on the server: the cache was emptied before PHP reread the files (14 §4, "The cache") |
TypeError: sem_get(): Argument #1 ($key) must be of type int on a cached page | semaphore key built as a string: from PHP 8 it's fatal even with @. cache_sem_get_params() in library/gallery/system/cache.php and getParams() in vendor/wolfgan/cache/services/sem.php must always return a 32-bit int |
| The page displays unreadable characters / binary hieroglyphs without PHP errors (HTTP 200) | HTTP double compression: the web server (Apache mod_deflate / OpenResty Brotli / Cloudflare) was compressing an already gzipped PHP response. With cm_can_compress() (library/gallery/system/compression.php), PHP detects upstream compression and serves plain HTML, leaving compression to the server (§2) |