Ir al contenido
JoeCMS Descargar 3.1.5
Manual · 12

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é guardaCómo se gobierna
de páginael HTML completo de una URLuse_cache(false) en el archivo; $schema["page"][...]["cache"] en el tema
de recursosCSS/JS concatenados y minificados, imágenes redimensionadasDEBUG_MODE, DISABLE_CACHE, CACHE_LAST_VERSION
de ajustesenrutamiento y configuraciones en memoriaCM_ENABLE_MEM_CACHING (hoy false), __CLEARCACHE__ en la URL
de aplicaciónlo 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 /srv y 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 con Cache-Control: no-store, no-cache, must-revalidate, sin Expires ni Last-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. El max-age es 3 en la respuesta que compone la página, y CM_PAGECACHE_GUEST_MAXAGE (por defecto 7, cm/conf/config.php) cuando llega de la caché de página (cache_parse() en library/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:

  1. ?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.
  2. 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.
  3. 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 .gz innecesarias en disco y sirve HTML en texto plano con readfile(). 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 (false para 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 si CM_ENABLE_MEM_CACHING está 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_ADAPTEREn PHP 8
no definido (false, el valor por defecto)ffGlobals: los datos duran lo que la petición, luego se pierden
apcda 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_*)
fsda error: pese al nombre no escribe en disco, es una copia de apc.php con las mismas apc_*
memcachedextensión memcached y un servidor Memcached
redisextensió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

  1. ¿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 es guest, no "sin caché".
  2. ¿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.
  3. ¿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).
  4. ¿Los recursos están minificados y concatenados? DEBUG_MODE encendido en producción lo desactiva.
  5. ¿El trabajo pesado es síncrono? Si lo es, pasarlo a cola o cron (05).
  6. CM_ENABLE_MEM_CACHING: útil solo con un adaptador redis o memcached (§3, §4); sin él, no cambia nada.
  7. Profiling: conf/profiling/ y library/gallery/system/trace.php recogen los tiempos (13).

6. Síntomas y causas

SíntomaCausa
"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 viejosfalta 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ódulohasta 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 otronivel de caché equivocado (guest/true en una página personal)
El idioma vuelve siempre al predeterminadointervención sobre el idioma fuera de language_pref_resolve()
Call to undefined function check_function() en language_preference.phpel 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 viejoenlace directo a /en/… en lugar de ?lang=: cambia la cookie, no el perfil
El CSS modificado no llega al navegadorcaché de recursos + Expires largo: subir CACHE_LAST_VERSION
He cambiado el enrutamiento y no pasa nadael XML modificado no se ha subido a producción
La imagen es la versión viejacaché de las variantes en cache/
Class "ffCacheAdapterAdapter" not found o Call to undefined function apc_store() en todas las páginasFF_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 arreglaopcache.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)