Media, images and files
Uploads, on-the-fly resizing, variant caching, file manager. It's one of the CMS's most useful subsystems, and one of those that break most silently.
1. showfiles: serving images
cm/showfiles.php is a standalone entry point (it doesn't go through index.php): it receives a path, finds the source file under FF_DISK_UPDIR, applies a transformation and serves the result, saving it in the cache so that next time Apache serves it directly.
The URL shape is:
/<image-path>/<mode>/<filename>
where <mode> is:
- a defined mode — the list comes from
ffMedia::getModes()and the<prefix>showfilestable; - or an on-the-fly size in the form
<width>x<height>(the code recognises thexand builds the parameters itself).
Two events let you step in when something is missing or wrong, registered in conf/config.php:
| Event | Handler | Use |
|---|---|---|
on_warning | showfiles_on_missing_resource($user_path, $referer, $mode) | missing resource: you can remap it, replace it with a placeholder, change mode |
on_error | showfiles_on_before_parsing_error($strError) | parsing error |
The project handler can be cms_showfiles_on_warning(), called by the system handler.
⚠️
display_errorsmust stay at0. A warning printed by PHP ends up inside the image's binary stream and corrupts it. It's the structural reason debugging on this stack is on demand (?__debug__) and not "on in development".
Variant cache
Generated images end up in cache/, and are served with a long Expires (365 days). Consequences:
- if the source file changes but not its name, the old variant stays: the cache must be emptied (see 12);
cache/must be writable, and must be excluded from the package and from content backups.
2. Uploads
| Point | What |
|---|---|
| Folder | uploads/ (the repo only has uploads/loghi, the rest is created on use). A PHP file or a script uploaded there doesn't run from the browser: the .htaccess answers 404 (14 §3) |
| Limit | MAX_UPLOAD in hook.php — currently practically unlimited (10000000000000000): the real limit is imposed by PHP's upload_max_filesize and post_max_size. A site changes it by defining it in the config |
| Widget | extended_type UploadImage / UploadFile on content fields (07 §3) |
| Helpers | library/gallery/common/set_field_uploader.php, get_file_properties.php, get_file_permission.php, fs_operation.php |
hook.php also has two helpers for remote files:
downloadRemoteFile($url, $destinationDir, $filename); // → array with outcome, mime, extension
saveRemoteImage($url_file, $nome_file, $relative_path);
with extractMimeType() and mimeToExtension() alongside.
Hygiene rule: an upload's extension is decided from the verified MIME, never from the name sent by the client. And the uploads folder must not execute PHP — that's what separates an upload from a webshell.
3. File manager
vendor/wolfgan/filemanager/Filemanager.php with fs_json, fs_php, fs_xml services: an abstraction for reading and writing structures on the filesystem. In the backend it's the engine of the resources area (/restricted/resources).
Writing is atomic: Filemanager::save() writes a temporary file next to the file and renames it, then invalidates the OPcache, so a concurrent request never includes a half-written file. If a PHP file is corrupted anyway, fs_php.php deletes it and the read returns the error instead of stopping the page: it is rebuilt on the next write. read($percorso, $chiavi) returns only the keys that exist (a missing key no longer returns null).
There's also library/gallery/common/check_fs.php and library/gallery/job.php with get_check_fs(): a recursive check of permissions and sizes of the file tree, used by diagnostics.
4. Thumbnails and images in content
| File | Role |
|---|---|
library/gallery/process/gallery_thumb.php, vgallery_thumb.php | generating thumbnails for lists |
library/gallery/common/get_thumb.php | calculation helper |
ff/classes/ffImage/ | the framework's image manipulation class |
library/Orientation-Fix-PHP-master/ | EXIF orientation correction |
The check_thumb() check is part of diagnostics (conf/gallery/job/diagnostic/).
5. Static assets
cm/static.php serves /themes, /uploads and /asset (mapped by the kernel). The minification and concatenation pipeline uses library/minify, gminify, cssmin, jsmin; it's controlled with DEBUG_MODE, DISABLE_CACHE and CACHE_LAST_VERSION.
The .htaccess generated by the installer also has rules for the media. and static. subdomains: if you want to serve media from a separate host (or from library/BunnyCDN/), that's the place. Installations from the ZIP get it from the wizard, jc_write_htaccess() in install/lib.php; those made with the old installer from conf/gallery/install/.htaccess-cms.tpl.
The media. subdomain
media.<domain>/<path> doesn't read from uploads/: it serves the copy in cache/.thumbs/<path>, which ff/classes/ffMedia.php creates (a hard link for originals, a new file for resized versions). When the copy is missing:
- if the original with the same path is in
uploads/, Apache serves it as it is, in ranges too (Range, which videos on iPhone need); - otherwise the request reaches the 404 and
cm/error.php, which hasffMedia::process()generate the copy and answers with a redirect: 302 to the same address, or 301 to the name the copy is saved under (1000-414/tags/x.jpg→tags/x-1000-414.jpg); - if the copy can't be created,
process()returnsfalseand the answer is a 404.
Point 1 also applies to /media/ on the main host.
⚠️ Three ways to send
media.images into a 500, all seen on grandchef on 28/9/2026:
- the rule that sends non-existent files to
index.phpalso applies tomedia., because it lists it or because the host condition isn't anchored:(www\.x\.com|x\.com)$without^also matchesmedia.x.com. The missing copy bounces between/index.phpand/cache/.thumbs/index.phpup to Apache's limit of 10 internal redirects (in the log: Request exceeded the limit of 10 internal redirects). The old installer's template is anchored; the wizard anchors it from 1.6.2 on, and before that it wrote(www\.x\.com|x\.com)$ [NC]in the# Front controllerblock. Hand-made.htaccessfiles must be checked;cache/.thumbs/gets emptied:bin/deploy.sh --svuota-cacheleaves it alone, anrm -rf cache/*doesn't;- point 1 is missing on a site installed before 28/9/2026: originals
ffMediacan't make a copy of (seen with JPGs and videos) get a 404, and before that date a permanent 301 to a truncated path (/prodotto-v2/intro.mp4→tto-v2/intro.mp4).
Sites already installed. The generated .htaccess isn't updated with the code: the deploy doesn't upload it (14). In the #media with SubDomains block you add by hand the condition RewriteCond %{REQUEST_URI} !^<FF_SITE_PATH>/uploads/ before the RewriteRule and, right after the block, the three lines of the point 1 rule. They're copied from conf/gallery/install/.htaccess-cms.tpl, replacing [FF_SITE_PATH] with the site's path, empty if the site sits at the root.
A .htaccess written by the wizard (at the top: generato dal wizard) has blocks with other names and, if it predates 1.6.2, the unanchored condition too. The # Immagini servite dal sotto-dominio media. block gets the same condition on uploads/; right after the block go the three lines of point 1; in the # Front controller block the host condition gets the leading ^. The exact text is what jc_write_htaccess() writes.
The commented-out rule #media:404 goto static is an alternative to point 2: it sends to the static. subdomain instead of cm/error.php. Until 28/9/2026 it had a typo (^!-f instead of !-f) that kept it from firing.
6. Common symptoms and causes
| Symptom | Likely cause |
|---|---|
| The image comes out corrupted or the browser says "invalid image" | a PHP warning printed into the stream: display_errors isn't 0 |
| The variant doesn't update after replacing the file | variant cache in cache/, with Expires at one year |
| 404 on a mode that exists | the mode isn't in the list (ffMedia::getModes() / showfiles table): use the WxH form |
| Upload failing with no message | PHP's upload_max_filesize/post_max_size, not MAX_UPLOAD |
| Images rotated after uploading from a phone | EXIF orientation not applied |
All media. images in 500, exceeded the limit of 10 internal redirects in the log | cache/.thumbs/ copies missing and a rule to index.php that also applies to media. (§5) |
A media. image or video answers 301 to a truncated address (tto-v2/…) | ffMedia::process() from before 28/9/2026 on an original it couldn't copy: update the code and add the §5 rule to the .htaccess |