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 laxy construye los parámetros por sí mismo).
Dos eventos permiten intervenir cuando algo falta o no va, registrados en conf/config.php:
| Evento | Handler | Uso |
|---|---|---|
on_warning | showfiles_on_missing_resource($user_path, $referer, $mode) | recurso ausente: se puede reasignar, sustituir por un marcador, cambiar mode |
on_error | showfiles_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_errorsdebe quedarse en0. 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
| Punto | Qué |
|---|---|
| Carpeta | uploads/ (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ímite | MAX_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 |
| Widget | extended_type UploadImage / UploadFile en los campos de los contenidos (07 §3) |
| Helpers | library/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
| Archivo | Función |
|---|---|
library/gallery/process/gallery_thumb.php, vgallery_thumb.php | generación de las miniaturas para las listas |
library/gallery/common/get_thumb.php | helper 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:
- 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); - si no, la petición llega al 404 y a
cm/error.php, que hace generar la copia affMedia::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); - si la copia no se puede crear,
process()devuelvefalsey 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.phplos archivos inexistentes vale también paramedia., porque lo enumera o porque la condición sobre el host no está anclada:(www\.x\.com|x\.com)$sin^vale también paramedia.x.com. La copia que falta rebota entre/index.phpy/cache/.thumbs/index.phphasta 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.htaccesshechos a mano hay que revisarlos;- se vacía
cache/.thumbs/:bin/deploy.sh --svuota-cachelo deja en paz, unrm -rf cache/*no;- falta el punto 1 en un sitio instalado antes del 28/9/2026: los originales de los que
ffMediano 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íntoma | Causa 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 archivo | caché de las variantes en cache/, con Expires a un año |
| 404 en un modo que existe | el modo no está en la lista (ffMedia::getModes() / tabla showfiles): usar la forma AnxAl |
| Upload que falla sin mensaje | upload_max_filesize/post_max_size de PHP, no MAX_UPLOAD |
| Imágenes giradas tras subirlas desde el teléfono | orientación EXIF no aplicada |
Todas las imágenes de media. en 500, en el log exceeded the limit of 10 internal redirects | faltan 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 |