Skip to content
JoeCMS Download 3.1.5
Manual · 11

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>showfiles table;
  • or an on-the-fly size in the form <width>x<height> (the code recognises the x and builds the parameters itself).

Two events let you step in when something is missing or wrong, registered in conf/config.php:

EventHandlerUse
on_warningshowfiles_on_missing_resource($user_path, $referer, $mode)missing resource: you can remap it, replace it with a placeholder, change mode
on_errorshowfiles_on_before_parsing_error($strError)parsing error

The project handler can be cms_showfiles_on_warning(), called by the system handler.

⚠️ display_errors must stay at 0. 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

PointWhat
Folderuploads/ (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)
LimitMAX_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
Widgetextended_type UploadImage / UploadFile on content fields (07 §3)
Helperslibrary/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

FileRole
library/gallery/process/gallery_thumb.php, vgallery_thumb.phpgenerating thumbnails for lists
library/gallery/common/get_thumb.phpcalculation 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:

  1. 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);
  2. otherwise the request reaches the 404 and cm/error.php, which has ffMedia::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);
  3. if the copy can't be created, process() returns false and 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.php also applies to media., because it lists it or because the host condition isn't anchored: (www\.x\.com|x\.com)$ without ^ also matches media.x.com. The missing copy bounces between /index.php and /cache/.thumbs/index.php up 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 controller block. Hand-made .htaccess files must be checked;
  • cache/.thumbs/ gets emptied: bin/deploy.sh --svuota-cache leaves it alone, an rm -rf cache/* doesn't;
  • point 1 is missing on a site installed before 28/9/2026: originals ffMedia can'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

SymptomLikely 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 filevariant cache in cache/, with Expires at one year
404 on a mode that existsthe mode isn't in the list (ffMedia::getModes() / showfiles table): use the WxH form
Upload failing with no messagePHP's upload_max_filesize/post_max_size, not MAX_UPLOAD
Images rotated after uploading from a phoneEXIF orientation not applied
All media. images in 500, exceeded the limit of 10 internal redirects in the logcache/.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