Vai al contenuto
JoeCMS Scarica 3.1.5
Manuale · 11

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 la x e costruisce i parametri da sé).

Due eventi permettono di intervenire quando qualcosa non c'è o non va, registrati in conf/config.php:

EventoHandlerUso
on_warningshowfiles_on_missing_resource($user_path, $referer, $mode)risorsa mancante: si può rimappare, sostituire con un segnaposto, cambiare mode
on_errorshowfiles_on_before_parsing_error($strError)errore di parsing

L'handler di progetto può essere cms_showfiles_on_warning(), richiamato dall'handler di sistema.

⚠️ display_errors deve restare a 0. 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

PuntoCosa
Cartellauploads/ (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)
LimiteMAX_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
Widgetextended_type UploadImage / UploadFile sui campi dei contenuti (07 §3)
Helperlibrary/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

FileRuolo
library/gallery/process/gallery_thumb.php, vgallery_thumb.phpgenerazione delle miniature per le liste
library/gallery/common/get_thumb.phphelper 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:

  1. 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);
  2. altrimenti la richiesta arriva al 404 e a cm/error.php, che fa generare la copia a ffMedia::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);
  3. se la copia non si può creare, process() restituisce false e 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.php i file inesistenti vale anche per media., perché lo elenca o perché la condizione sull'host non è ancorata: (www\.x\.com|x\.com)$ senza ^ vale anche per media.x.com. La copia mancante rimbalza fra /index.php e /cache/.thumbs/index.php fino 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 .htaccess fatti a mano vanno controllati;
  • si svuota cache/.thumbs/: bin/deploy.sh --svuota-cache lo lascia stare, un rm -rf cache/* no;
  • manca il punto 1 su un sito installato prima del 28/9/2026: gli originali di cui ffMedia non 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

SintomoCausa 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 filecache delle varianti in cache/, con Expires a un anno
404 su un modo che esisteil modo non è nell'elenco (ffMedia::getModes() / tabella showfiles): usare la forma LxA
Upload che fallisce senza messaggioupload_max_filesize/post_max_size di PHP, non MAX_UPLOAD
Immagini ruotate dopo l'upload da telefonoorientamento EXIF non applicato
Tutte le immagini di media. in 500, nel log exceeded the limit of 10 internal redirectscopie 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