Media, immagini e file
Upload, ridimensionamento on-the-fly, cache delle varianti, filemanager. È uno dei sottosistemi più utili del CMS, e uno di quelli che si rompono più silenziosamente.
1. showfiles: il serving delle immagini
cm/showfiles.php è un entry point autonomo (non passa da index.php): riceve un percorso, individua il file sorgente sotto FF_DISK_UPDIR, applica una trasformazione e serve il risultato, salvandolo in cache così che la volta dopo lo serva direttamente Apache.
La forma dell'URL è:
/<percorso-immagine>/<modo>/<nomefile>
dove <modo> è:
- un modo definito — l'elenco viene da
ffMedia::getModes()e dalla tabella<prefisso>showfiles; - oppure una misura al volo nella forma
<larghezza>x<altezza>(il codice riconosce laxe costruisce i parametri da sé).
Due eventi permettono di intervenire quando qualcosa non c'è o non va, registrati in conf/config.php:
| Evento | Handler | Uso |
|---|---|---|
on_warning | showfiles_on_missing_resource($user_path, $referer, $mode) | risorsa mancante: si può rimappare, sostituire con un segnaposto, cambiare mode |
on_error | showfiles_on_before_parsing_error($strError) | errore di parsing |
L'handler di progetto può essere cms_showfiles_on_warning(), richiamato dall'handler di sistema.
⚠️
display_errorsdeve restare a0. Un warning stampato da PHP finisce dentro il flusso binario dell'immagine e la corrompe. È la ragione strutturale per cui il debug su questo stack è on-demand (?__debug__) e non "acceso in sviluppo".
Cache delle varianti
Le immagini generate finiscono in cache/, e vengono servite con Expires lungo (365 giorni). Conseguenze:
- se cambia il file sorgente ma non il nome, la variante vecchia resta: serve svuotare la cache (vedi 12);
cache/deve essere scrivibile, e va esclusa dal pacchetto e dai backup dei contenuti.
2. Upload
| Punto | Cosa |
|---|---|
| Cartella | uploads/ (nel repo c'è solo uploads/loghi, il resto nasce all'uso). Un PHP o uno script caricato lì non si esegue dal browser: il .htaccess risponde 404 (14 §3) |
| Limite | MAX_UPLOAD in hook.php — oggi praticamente illimitato (10000000000000000): il limite reale lo impongono upload_max_filesize e post_max_size di PHP. Un sito lo cambia definendolo nel config |
| Widget | extended_type UploadImage / UploadFile sui campi dei contenuti (07 §3) |
| Helper | library/gallery/common/set_field_uploader.php, get_file_properties.php, get_file_permission.php, fs_operation.php |
Da hook.php ci sono anche due helper per i file remoti:
downloadRemoteFile($url, $destinationDir, $filename); // → array con esito, mime, estensione
saveRemoteImage($url_file, $nome_file, $relative_path);
con extractMimeType() e mimeToExtension() a corredo.
Regola di igiene: l'estensione di un upload si decide dal MIME verificato, mai dal nome mandato dal client. E la cartella degli upload non deve eseguire PHP — è ciò che separa un upload da una webshell.
3. Filemanager
vendor/wolfgan/filemanager/Filemanager.php con servizi fs_json, fs_php, fs_xml: astrazione per leggere e scrivere strutture su filesystem. Nel backend è il motore dell'area risorse (/restricted/resources).
La scrittura è atomica: Filemanager::save() scrive un temporaneo accanto al file e lo rinomina, poi invalida l'OPcache, così una richiesta concorrente non include mai un file a metà. Se un file PHP è comunque corrotto, fs_php.php lo cancella e la lettura torna l'errore invece di fermare la pagina: alla scrittura successiva si rifà. read($percorso, $chiavi) torna solo le chiavi che ci sono (una chiave assente non torna più null).
C'è anche library/gallery/common/check_fs.php e library/gallery/job.php con get_check_fs(): verifica ricorsiva di permessi e dimensioni dell'albero dei file, usata dalla diagnostica.
4. Thumbnail e immagini nei contenuti
| File | Ruolo |
|---|---|
library/gallery/process/gallery_thumb.php, vgallery_thumb.php | generazione delle miniature per le liste |
library/gallery/common/get_thumb.php | helper di calcolo |
ff/classes/ffImage/ | la classe di manipolazione immagine del framework |
library/Orientation-Fix-PHP-master/ | correzione dell'orientamento EXIF |
Il controllo check_thumb() fa parte della diagnostica (conf/gallery/job/diagnostic/).
5. Asset statici
cm/static.php serve /themes, /uploads e /asset (mappati dal kernel). La pipeline di minificazione e concatenazione usa library/minify, gminify, cssmin, jsmin; si governa con DEBUG_MODE, DISABLE_CACHE e CACHE_LAST_VERSION.
Nel .htaccess generato dall'installer ci sono anche le regole per i sotto-domini media. e static.: se si vuole servire i media da un host separato (o da library/BunnyCDN/), il posto è quello. Le installazioni dallo ZIP lo ricevono dal wizard, jc_write_htaccess() in install/lib.php; quelle fatte col vecchio installer da conf/gallery/install/.htaccess-cms.tpl.
Il sotto-dominio media.
media.<dominio>/<percorso> non legge da uploads/: serve la copia in cache/.thumbs/<percorso>, che ff/classes/ffMedia.php crea (un hard link per gli originali, un file nuovo per le versioni ridimensionate). Quando la copia manca:
- se in
uploads/c'è l'originale con lo stesso percorso, lo serve Apache così com'è, anche a pezzi (Range, che serve ai video su iPhone); - altrimenti la richiesta arriva al 404 e a
cm/error.php, che fa generare la copia affMedia::process()e risponde con un redirect: 302 allo stesso indirizzo, oppure 301 al nome con cui la copia è salvata (1000-414/tags/x.jpg→tags/x-1000-414.jpg); - se la copia non si può creare,
process()restituiscefalsee la risposta è un 404.
Il punto 1 vale anche per /media/ sull'host principale.
⚠️ Tre modi per mandare in 500 le immagini di
media., visti tutti su grandchef il 28/9/2026:
- la regola che manda a
index.phpi file inesistenti vale anche permedia., perché lo elenca o perché la condizione sull'host non è ancorata:(www\.x\.com|x\.com)$senza^vale anche permedia.x.com. La copia mancante rimbalza fra/index.phpe/cache/.thumbs/index.phpfino al limite dei 10 redirect interni di Apache (nel log: Request exceeded the limit of 10 internal redirects). Il modello del vecchio installer è ancorato; il wizard lo è dalla 1.6.2, prima scriveva(www\.x\.com|x\.com)$ [NC]nel blocco# Front controller. I.htaccessfatti a mano vanno controllati;- si svuota
cache/.thumbs/:bin/deploy.sh --svuota-cachelo lascia stare, unrm -rf cache/*no;- manca il punto 1 su un sito installato prima del 28/9/2026: gli originali di cui
ffMedianon riesce a creare la copia (visto con JPG e video) ricevono un 404, e prima di questa data un 301 permanente verso un percorso troncato (/prodotto-v2/intro.mp4→tto-v2/intro.mp4).
Siti già installati. Il .htaccess generato non si aggiorna con il codice: il deploy non lo carica (14). Nel blocco #media with SubDomains si aggiungono a mano la condizione RewriteCond %{REQUEST_URI} !^<FF_SITE_PATH>/uploads/ prima della RewriteRule e, subito dopo il blocco, le tre righe della regola del punto 1. Si copiano da conf/gallery/install/.htaccess-cms.tpl sostituendo [FF_SITE_PATH] con il percorso del sito, vuoto se il sito sta nella radice.
Un .htaccess scritto dal wizard (in testa: generato dal wizard) ha blocchi con altri nomi e, se è di prima della 1.6.2, anche la condizione non ancorata. Nel blocco # Immagini servite dal sotto-dominio media. va la stessa condizione su uploads/; subito dopo il blocco, le tre righe del punto 1; nel blocco # Front controller la condizione sull'host prende la ^ iniziale. Il testo esatto è quello che scrive jc_write_htaccess().
La regola commentata #media:404 goto static è un'alternativa al punto 2: manda al sotto-dominio static. invece che a cm/error.php. Fino al 28/9/2026 aveva un refuso (^!-f invece di !-f) che le impediva di scattare.
6. Sintomi e cause frequenti
| Sintomo | Causa probabile |
|---|---|
| L'immagine esce corrotta o il browser dice "immagine non valida" | un warning PHP stampato nel flusso: display_errors non è 0 |
| La variante non si aggiorna dopo aver sostituito il file | cache delle varianti in cache/, con Expires a un anno |
| 404 su un modo che esiste | il modo non è nell'elenco (ffMedia::getModes() / tabella showfiles): usare la forma LxA |
| Upload che fallisce senza messaggio | upload_max_filesize/post_max_size di PHP, non MAX_UPLOAD |
| Immagini ruotate dopo l'upload da telefono | orientamento EXIF non applicato |
Tutte le immagini di media. in 500, nel log exceeded the limit of 10 internal redirects | copie di cache/.thumbs/ mancanti e regola verso index.php valida anche per media. (§5) |
Un'immagine o un video di media. risponde 301 verso un indirizzo troncato (tto-v2/…) | ffMedia::process() di prima del 28/9/2026 su un originale di cui non riusciva a creare la copia: aggiornare il codice e aggiungere al .htaccess la regola del §5 |