Ir al contenido
JoeCMS Descargar 3.1.5
Manual · 11

Medios, imágenes y archivos

Upload, redimensionado al vuelo, caché de las variantes, filemanager. Es uno de los subsistemas más útiles del CMS, y uno de los que se rompen de forma más silenciosa.

1. showfiles: servir las imágenes

cm/showfiles.php es un punto de entrada autónomo (no pasa por index.php): recibe una ruta, localiza el archivo fuente bajo FF_DISK_UPDIR, aplica una transformación y sirve el resultado, guardándolo en caché para que la vez siguiente lo sirva directamente Apache.

La forma de la URL es:

/<ruta-imagen>/<modo>/<nombrearchivo>

donde <modo> es:

  • un modo definido — la lista viene de ffMedia::getModes() y de la tabla <prefijo>showfiles;
  • o bien una medida al vuelo con la forma <ancho>x<alto> (el código reconoce la x y construye los parámetros por sí mismo).

Dos eventos permiten intervenir cuando algo falta o no va, registrados en conf/config.php:

EventoHandlerUso
on_warningshowfiles_on_missing_resource($user_path, $referer, $mode)recurso ausente: se puede reasignar, sustituir por un marcador, cambiar mode
on_errorshowfiles_on_before_parsing_error($strError)error de parsing

El handler de proyecto puede ser cms_showfiles_on_warning(), llamado por el handler de sistema.

⚠️ display_errors debe quedarse en 0. Un warning impreso por PHP acaba dentro del flujo binario de la imagen y la corrompe. Es la razón estructural por la que el debug en este stack es bajo demanda (?__debug__) y no "encendido en desarrollo".

Caché de las variantes

Las imágenes generadas acaban en cache/, y se sirven con Expires largo (365 días). Consecuencias:

  • si cambia el archivo fuente pero no el nombre, la variante vieja se queda: hay que vaciar la caché (ver 12);
  • cache/ debe tener permisos de escritura, y debe excluirse del paquete y de los backups de contenidos.

2. Upload

PuntoQué
Carpetauploads/ (en el repo solo está uploads/loghi, el resto nace con el uso). Un PHP o un script subido allí no se ejecuta desde el navegador: el .htaccess responde 404 (14 §3)
LímiteMAX_UPLOAD en hook.php — hoy prácticamente ilimitado (10000000000000000): el límite real lo imponen upload_max_filesize y post_max_size de PHP. Un sitio lo cambia definiéndolo en el config
Widgetextended_type UploadImage / UploadFile en los campos de los contenidos (07 §3)
Helperslibrary/gallery/common/set_field_uploader.php, get_file_properties.php, get_file_permission.php, fs_operation.php

En hook.php hay también dos helpers para los archivos remotos:

downloadRemoteFile($url, $destinationDir, $filename);   // → array con resultado, mime, extensión
saveRemoteImage($url_file, $nome_file, $relative_path);

con extractMimeType() y mimeToExtension() como complemento.

Regla de higiene: la extensión de un upload se decide a partir del MIME verificado, nunca del nombre enviado por el cliente. Y la carpeta de uploads no debe ejecutar PHP — es lo que separa un upload de una webshell.

3. Filemanager

vendor/wolfgan/filemanager/Filemanager.php con los servicios fs_json, fs_php, fs_xml: abstracción para leer y escribir estructuras en el filesystem. En el backend es el motor del área de recursos (/restricted/resources).

La escritura es atómica: Filemanager::save() escribe un temporal junto al archivo y lo renombra, luego invalida la OPcache, así una petición concurrente nunca incluye un archivo a medias. Si un archivo PHP está corrupto de todos modos, fs_php.php lo borra y la lectura devuelve el error en lugar de detener la página: en la escritura siguiente se rehace. read($percorso, $chiavi) devuelve solo las claves que existen (una clave ausente ya no devuelve null).

Está también library/gallery/common/check_fs.php y library/gallery/job.php con get_check_fs(): verificación recursiva de permisos y tamaños del árbol de archivos, usada por el diagnóstico.

4. Miniaturas e imágenes en los contenidos

ArchivoFunción
library/gallery/process/gallery_thumb.php, vgallery_thumb.phpgeneración de las miniaturas para las listas
library/gallery/common/get_thumb.phphelper de cálculo
ff/classes/ffImage/la clase de manipulación de imágenes del framework
library/Orientation-Fix-PHP-master/corrección de la orientación EXIF

El control check_thumb() forma parte del diagnóstico (conf/gallery/job/diagnostic/).

5. Recursos estáticos

cm/static.php sirve /themes, /uploads y /asset (mapeados por el kernel). La pipeline de minificación y concatenación usa library/minify, gminify, cssmin, jsmin; se gobierna con DEBUG_MODE, DISABLE_CACHE y CACHE_LAST_VERSION.

En el .htaccess generado por el instalador están también las reglas para los subdominios media. y static.: si se quiere servir los medios desde un host separado (o desde library/BunnyCDN/), el sitio es ese. Las instalaciones desde el ZIP lo reciben del asistente, jc_write_htaccess() en install/lib.php; las hechas con el antiguo instalador, de conf/gallery/install/.htaccess-cms.tpl.

El subdominio media.

media.<dominio>/<ruta> no lee de uploads/: sirve la copia en cache/.thumbs/<ruta>, que ff/classes/ffMedia.php crea (un hard link para los originales, un archivo nuevo para las versiones redimensionadas). Cuando falta la copia:

  1. si en uploads/ está el original con la misma ruta, lo sirve Apache tal cual, también por partes (Range, que necesitan los vídeos en iPhone);
  2. si no, la petición llega al 404 y a cm/error.php, que hace generar la copia a ffMedia::process() y responde con un redirect: 302 a la misma dirección, o 301 al nombre con el que se guarda la copia (1000-414/tags/x.jpg → tags/x-1000-414.jpg);
  3. si la copia no se puede crear, process() devuelve false y la respuesta es un 404.

El punto 1 vale también para /media/ en el host principal.

⚠️ Tres maneras de mandar a 500 las imágenes de media., vistas todas en grandchef el 28/9/2026:

  • la regla que manda a index.php los archivos inexistentes vale también para media., porque lo enumera o porque la condición sobre el host no está anclada: (www\.x\.com|x\.com)$ sin ^ vale también para media.x.com. La copia que falta rebota entre /index.php y /cache/.thumbs/index.php hasta el límite de 10 redirecciones internas de Apache (en el log: Request exceeded the limit of 10 internal redirects). La plantilla del antiguo instalador está anclada; el asistente la ancla desde la 1.6.2, antes escribía (www\.x\.com|x\.com)$ [NC] en el bloque # Front controller. Los .htaccess hechos a mano hay que revisarlos;
  • se vacía cache/.thumbs/: bin/deploy.sh --svuota-cache lo deja en paz, un rm -rf cache/* no;
  • falta el punto 1 en un sitio instalado antes del 28/9/2026: los originales de los que ffMedia no consigue crear la copia (visto con JPG y vídeos) reciben un 404, y antes de esa fecha un 301 permanente hacia una ruta truncada (/prodotto-v2/intro.mp4 → tto-v2/intro.mp4).

Sitios ya instalados. El .htaccess generado no se actualiza con el código: el despliegue no lo sube (14). En el bloque #media with SubDomains se añaden a mano la condición RewriteCond %{REQUEST_URI} !^<FF_SITE_PATH>/uploads/ antes de la RewriteRule y, justo después del bloque, las tres líneas de la regla del punto 1. Se copian de conf/gallery/install/.htaccess-cms.tpl sustituyendo [FF_SITE_PATH] por la ruta del sitio, vacía si el sitio está en la raíz.

Un .htaccess escrito por el asistente (al principio: generato dal wizard) tiene bloques con otros nombres y, si es anterior a la 1.6.2, también la condición sin anclar. En el bloque # Immagini servite dal sotto-dominio media. va la misma condición sobre uploads/; justo después del bloque, las tres líneas del punto 1; en el bloque # Front controller la condición sobre el host recibe el ^ inicial. El texto exacto es el que escribe jc_write_htaccess().

La regla comentada #media:404 goto static es una alternativa al punto 2: manda al subdominio static. en lugar de a cm/error.php. Hasta el 28/9/2026 tenía una errata (^!-f en lugar de !-f) que le impedía activarse.

6. Síntomas y causas frecuentes

SíntomaCausa probable
La imagen sale corrupta o el navegador dice "imagen no válida"un warning PHP impreso en el flujo: display_errors no está a 0
La variante no se actualiza tras sustituir el archivocaché de las variantes en cache/, con Expires a un año
404 en un modo que existeel modo no está en la lista (ffMedia::getModes() / tabla showfiles): usar la forma AnxAl
Upload que falla sin mensajeupload_max_filesize/post_max_size de PHP, no MAX_UPLOAD
Imágenes giradas tras subirlas desde el teléfonoorientación EXIF no aplicada
Todas las imágenes de media. en 500, en el log exceeded the limit of 10 internal redirectsfaltan copias de cache/.thumbs/ y la regla hacia index.php vale también para media. (§5)
Una imagen o un vídeo de media. responde 301 hacia una dirección truncada (tto-v2/…)ffMedia::process() anterior al 28/9/2026 sobre un original del que no conseguía crear la copia: actualizar el código y añadir al .htaccess la regla del §5