Caché y rendimiento
El CMS tiene cuatro cachés distintas, con interruptores diferentes. Confundirlas es la causa más común del "he modificado y no cambia nada" y de su gemelo, "el usuario ve la página de otro".
1. Las cuatro cachés
| Caché | Qué guarda | Cómo se gobierna |
|---|---|---|
| de página | el HTML completo de una URL | use_cache(false) en el archivo; $schema["page"][...]["cache"] en el tema |
| de recursos | CSS/JS concatenados y minificados, imágenes redimensionadas | DEBUG_MODE, DISABLE_CACHE, CACHE_LAST_VERSION |
| de ajustes | enrutamiento y configuraciones en memoria | CM_ENABLE_MEM_CACHING (hoy false), __CLEARCACHE__ en la URL |
| de aplicación | lo que pongas tú | ffCache (vendor/phpformsframework/ffCache/): sin adaptador dura una petición (§4) |
2. Caché de página
Desactivarla para una página o un servicio
use_cache(false); // library/gallery/common.php:369
Obligatorio al principio de:
- toda página dinámica (contenido que depende del usuario, de la sesión, de la hora);
- todos los servicios
/srvy los endpoints API — sin él, el CMS puede servir una respuesta vieja a una llamada autenticada.
Los POST nunca pasan por la caché de página, ni en lectura ni en escritura: check_static_cache_page() (library/gallery/system/cache.php) los descarta primero y define DISABLE_CACHE. La clave de un archivo en caché contiene los parámetros de la petición (index_email-…_XHR.gz), así que hasta la 3.1.2 la respuesta a un envío se guardaba y luego se devolvía a cualquiera que reenviara los mismos campos, aunque fuera equivocada. Los GET, XHR incluidos, se siguen guardando como antes.
Qué sale en la respuesta
use_cache(false) apaga la caché del CMS (ningún archivo, ninguna copia reutilizada por el CMS): hay que decírselo también al navegador y a las cachés intermedias, o durante unos segundos se quedan ellas con la página.
- página personal (quien ha entrado con su cuenta, o
use_cache(false)): la respuesta sale conCache-Control: no-store, no-cache, must-revalidate, sinExpiresniLast-Modified(library/gallery/system/set_cache_page.php,library/gallery/system/cache.php); - página pública vista por un invitado: sigue siendo
public— es a propósito, durante unos segundos el navegador no la vuelve a pedir. Elmax-agees3en la respuesta que compone la página, yCM_PAGECACHE_GUEST_MAXAGE(por defecto7,cm/conf/config.php) cuando llega de la caché de página (cache_parse()enlibrary/gallery/system/cache.php). Un sitio con contenidos que no cambian de un minuto a otro lo sube en la config de entorno (config.remote.php), sin tocar el código.
El defecto que hizo necesaria esta línea: las páginas del área salían igualmente con public, max-age=3, y durante tres segundos el navegador reutilizaba la copia recién vista — tras salir se volvía a ver el área, y una caché compartida habría podido servirla a otra persona.
Lo que el PHP no declara lo decide Apache. El .htaccess del sitio (lo escribe el instalador, jc_htaccess_static_tail() en install/lib.php) tiene mod_expires con ExpiresByType text/html "access plus 0 seconds": un controlador de módulo, un script a medida o una redirección hecha con header('Location: …') sin cabeceras de caché no se quedan en el navegador. Hasta la 3.1.0 la línea era "access plus 1 week", y Apache añadía max-age=604800 incluso junto al del PHP: la redirección de un módulo hacia el login se quedaba una semana en el navegador y, tras el acceso, el navegador volvía al login por su cuenta sin preguntar nada al sitio (JoeDesk, 2026-10-22). El despliegue nunca sube el .htaccess (bin/deploy.sh, 14): en un sitio instalado antes la línea hay que cambiarla a mano. Un módulo, en cualquier caso, declara la caché de sus respuestas — no-store para todo lo que depende de quién ha entrado, redirecciones incluidas.
Declarar su nivel
En themes/<tema>/settings.php:
$schema["page"]["/"] = array("name" => "public", "cache" => "guest");
Valores admitidos (documentados en library/gallery/settings.php): user, group, guest, true, false, o una ruta que empieza por /.
guest— una sola copia, servida a los usuarios anónimos; quien está conectado la salta;user— una copia por usuario;group— una copia por grupo;false— nunca en caché.
En el mismo archivo, $schema["request"]["/ruta"]["nocache"] apaga la caché por petición (true siempre, un array solo si en la query hay uno de esos parámetros): es la vía para las respuestas que dependen del usuario y no deben acabar en una caché compartida, como /OneSignalIdentity. Ver 01 §5.
Multilingüe
La caché es por idioma: el idioma lo decide el prefijo de la URL (/en/…), y de FF_LOCALE dependen slugs, diccionario, plantillas y clave de caché. Para cambiar de idioma se cambia de URL.
La persistencia de la elección (cookie lang, preferencia en el perfil, redirect 302 hacia la URL con prefijo) está en un solo punto: language_pref_resolve() en library/gallery/common/language_preference.php. La llama el kernel (vendor/wolfgan/cms/services/kernel.php) justo después de Auth::check(): la sesión ya existe, aún no hay salida, y la página todavía no ha pasado por la caché, así que la atraviesan también las páginas no cacheables. cache_check_lang() en library/gallery/system/cache.php queda como entrada histórica y remite al resolvedor, que se ejecuta una sola vez por petición.
Orden de resolución, gana el primero que responde:
?lang=<CODE|tiny>— elección explícita: escribe la cookie y, si el usuario está autenticado, el perfil; luego 302 a la URL del idioma elegido, sin?lang=. El selector[LANGUAGE_SWITCHER](library/gallery/process/language.php) enlaza siempre así, también para el idioma predeterminado: un enlace directo a/en/…cambiaría la página pero no el idioma en el que el usuario recibe los emails.- URL ya con prefijo — alinea solo la cookie. El perfil no se toca: abrir un enlace ajeno en inglés no debe cambiar el idioma de las comunicaciones.
- URL canónica — perfil (si está autenticado) → cookie →
Accept-Language(solo en la raíz/y solo si aún no hay una elección) → predeterminado. Un idioma no predeterminado lleva a un 302.
Nunca se ejecuta en XHR, con métodos distintos de GET, en un sitio con un solo idioma activo, ni en las rutas de servicio (/restricted, /admin, /api, /srv, /cronjob, /media, /static, recursos con extensión). Siempre 302, nunca 301: un 301 se quedaría en la caché del navegador. Si la página no existe en el idioma pedido se queda donde está. Constantes opcionales, no definidas por defecto: JC_LANG_COOKIE (nombre de la cookie) y JC_LANG_AUTODETECT (false apaga la detección desde Accept-Language).
Fue una elección pagada: dos implementaciones de lo mismo — una en el init y otra en la capa de caché — producían URL corruptas. Si hay que tocar el idioma, se toca en el resolvedor y solo ahí.
Para el idioma de emails y notificaciones ver 06 §2.
Canonical y sitemap por idioma. Una página de archivo en un idioma no predeterminado declara como canonical su propia dirección traducida (/en/contact, no /contattaci): set_header_page() (library/gallery/common/set_header_page.php) la obtiene con content_i18n_url() a partir de los slugs de contents/i18n.php. Las páginas de vgallery tienen permalinks propios y no pasan por ahí. El sitemap (modules/cms-common/models/Sitemap.php) lista cada página de archivo y la página de inicio una vez por idioma activo, con <xhtml:link rel="alternate" hreflang>, en las mismas direcciones que los canonical. Con un solo idioma no cambia nada. Detalles y límites en GUIDA_SITEMAP.md.
Compresión y prevención de la doble compresión
JoeCMS admite tanto la compresión delegada en el servidor web (el estándar en servidores modernos con mod_brotli o mod_deflate, en Cloudflare y en proxies inversos como OpenResty), como la compresión directa mediante PHP (gzencode()) para alojamientos mínimos que no la proporcionan.
La función cm_can_compress() en library/gallery/system/compression.php detecta automáticamente si el servidor web señala que gestiona la compresión (a través de SERVER_COMPRESSION configurado en .htaccess, módulos de Apache mod_brotli/mod_deflate, proxy OpenResty, cabeceras de Cloudflare o zlib.output_compression en php.ini):
- Si el servidor gestiona la compresión: PHP no realiza compresión a nivel de aplicación, no genera copias
.gzinnecesarias en disco y sirve HTML en texto plano conreadfile(). El servidor comprime una sola vez y el navegador recibe la página intacta. - Si el servidor NO comprime y el cliente admite gzip: PHP comprime el HTML mediante gzip y la caché guarda y sirve el archivo precomprimido para maximizar el rendimiento.
- Es posible forzar este comportamiento con la constante
CM_ENABLE_GZIP(falsepara desactivar la compresión de PHP en cualquier circunstancia).
Invalidar
refresh_cache($namespace, $node, $action, $path, $tags, $cats); // library/gallery/common/refresh_cache.php
refresh_cache_by_path($path);
update_vgallery ya la llama cuando se guarda un contenido: es otro motivo para no reimplementar el guardado (07 §3).
Vía bus de servicios está también la invalidación asíncrona: Jobs::async("/api/cache/refresh", array("url" => …)).
Y a mano, cuando hace falta el martillo: vaciar cache/. Es lo que hace el instalador al final del asistente, porque las páginas cacheadas durante la instalación contendrían tokens aún no resueltos.
3. Caché de ajustes y enrutamiento
CM_ENABLE_MEM_CACHING es false en conf/gallery/config.php, y se puede sobrescribir desde la config de entorno. Significa que el router relee los XML en cada petición que llega hasta él (las páginas servidas desde la caché de página no llegan):
- ✅ los cambios al enrutamiento son inmediatos, nada que vaciar;
- ❌ se paga la lectura de los XML, unos pocos milisegundos, en las peticiones fuera de caché;
- ⚠️
__CLEARCACHE__en la URL funciona solo siCM_ENABLE_MEM_CACHINGestá activo (cm/cm.php:255).
Activarla solo tiene sentido con un adaptador que conserve los datos de una petición a otra (§4): sin FF_CACHE_ADAPTER la «memoria» es ffGlobals y se pierde al final de la petición, así que no se ahorra nada; con apc o fs en PHP 8 el sitio da error en la primera petición. Con redis o memcached el recorrido funciona (cmRouter::loadMem() y cmRouter::orderRules() en cm/cmRouter.php), pero la ganancia sigue siendo de pocos milisegundos, solo en las peticiones fuera de caché, y exige el procedimiento de vaciado en el despliegue: normalmente no merece la pena.
4. ffCache: la caché de aplicación
ffCache tiene adaptadores intercambiables, elegidos con FF_CACHE_ADAPTER en la config de entorno. Con COMPOSER_PATH (los sitios instalados con el asistente) funciona la copia de vendor/phpformsframework/ffCache/; la de ff/classes/ffCache/ solo sirve sin él.
FF_CACHE_ADAPTER | En PHP 8 |
|---|---|
no definido (false, el valor por defecto) | ffGlobals: los datos duran lo que la petición, luego se pierden |
apc | da error: apc.php extiende ffCacheAdapterAdapter, una clase que no existe, y llama a apc_store()/apc_fetch(), que APCu en PHP 8 no tiene (solo apcu_*) |
fs | da error: pese al nombre no escribe en disco, es una copia de apc.php con las mismas apc_* |
memcached | extensión memcached y un servidor Memcached |
redis | extensión redis y un servidor Redis (FF_CACHE_REDIS_SERVER, FF_CACHE_REDIS_PORT) |
Más vendor/wolfgan/cache/ con los servicios page, sem (semáforos) y shield.
La usan el router (solo con CM_ENABLE_MEM_CACHING, §3), las plantillas y el traductor del framework: sin adaptador, para todos ellos es una caché de la petición individual. Instalar APCu en el servidor no cambia nada, porque ningún adaptador lo llama. Para una caché de aplicación del proyecto (resultados costosos, respuestas de API externas, recuentos) que sobreviva a la petición, en un servidor con APCu el camino que funciona hoy es llamar directamente a apcu_fetch()/apcu_store(), con function_exists() delante: el módulo es opcional, y donde falta simplemente no hay caché.
5. Rendimiento: qué mirar, en orden
- ¿La página está en caché? Una página pública que hace
use_cache(false)"por seguridad" es la primera causa de lentitud. El nivel correcto esguest, no "sin caché". - ¿Cuántas queries hace? El modelo vgallery es de campos dinámicos: una lista ingenua hace una query por nodo. Se pasa por los helpers (
get_vgallery_card,get_schema_fields_by_type) y se mide. - ¿Las imágenes tienen un modo? Servir el original de 4 MB donde hace falta una miniatura de 40 KB es la ganancia más grande y más fácil (11).
- ¿Los recursos están minificados y concatenados?
DEBUG_MODEencendido en producción lo desactiva. - ¿El trabajo pesado es síncrono? Si lo es, pasarlo a cola o cron (05).
CM_ENABLE_MEM_CACHING: útil solo con un adaptadorredisomemcached(§3, §4); sin él, no cambia nada.- Profiling:
conf/profiling/ylibrary/gallery/system/trace.phprecogen los tiempos (13).
6. Síntomas y causas
| Síntoma | Causa |
|---|---|
| "He modificado la plantilla y no cambia nada" | caché de página; o el bloque no está parseado (02 §2) |
| Un endpoint JSON devuelve datos viejos | falta use_cache(false) |
Un formulario enviado por ajax recibe el HTML de la página de inicio (<div id="L1" class="applets block">) en lugar del JSON del módulo | hasta la 3.1.2: POST XHR desde una página con secciones propias, atrapado por el atajo XHR de library/gallery/system/init.php (01) y luego guardado en caché con los campos del formulario en la clave. Desde la 3.1.3 los POST ya no toman ese camino y no entran en caché (§2) |
| Un usuario ve los datos de otro | nivel de caché equivocado (guest/true en una página personal) |
| El idioma vuelve siempre al predeterminado | intervención sobre el idioma fuera de language_pref_resolve() |
Call to undefined function check_function() en language_preference.php | el kernel llama al resolvedor antes de library/gallery/common.php: ocurre en las áreas reservadas con ruta propia (/gestione, no /restricted), que no están en la lista de rutas omitidas. El resolvedor ahora carga get_locale() por sí mismo (language_pref_has_locale()) |
| El usuario cambia de idioma pero los emails llegan en el viejo | enlace directo a /en/… en lugar de ?lang=: cambia la cookie, no el perfil |
| El CSS modificado no llega al navegador | caché de recursos + Expires largo: subir CACHE_LAST_VERSION |
| He cambiado el enrutamiento y no pasa nada | el XML modificado no se ha subido a producción |
| La imagen es la versión vieja | caché de las variantes en cache/ |
Class "ffCacheAdapterAdapter" not found o Call to undefined function apc_store() en todas las páginas | FF_CACHE_ADAPTER puesto a apc o fs en PHP 8: se quita de la config de entorno (§4) |
| Tras el despliegue las páginas en caché aún tienen textos o código viejos, y vaciarlas otra vez lo arregla | opcache.revalidate_freq alto en el servidor: la caché se vació antes de que PHP releyera los archivos (14 §4, «La caché») |
TypeError: sem_get(): Argument #1 ($key) must be of type int en una página en caché | clave del semáforo construida como cadena: desde PHP 8 es fatal incluso con @. cache_sem_get_params() en library/gallery/system/cache.php y getParams() en vendor/wolfgan/cache/services/sem.php deben devolver siempre un int de 32 bits |
| La página muestra caracteres ilegibles / jeroglíficos binarios sin errores de PHP (HTTP 200) | doble compresión HTTP: el servidor web (Apache mod_deflate / OpenResty Brotli / Cloudflare) comprimía una respuesta ya comprimida con gzip por PHP. Con cm_can_compress() (library/gallery/system/compression.php), PHP detecta la compresión previa y sirve HTML en plano dejando la compresión al servidor (§2) |