Médias, images et fichiers
Upload, redimensionnement à la volée, cache des variantes, gestionnaire de fichiers. C'est l'un des sous-systèmes les plus utiles du CMS, et l'un de ceux qui cassent le plus silencieusement.
1. showfiles : le service des images
cm/showfiles.php est un point d'entrée autonome (il ne passe pas par index.php) : il reçoit un chemin, trouve le fichier source sous FF_DISK_UPDIR, applique une transformation et sert le résultat, en l'enregistrant en cache pour que la fois suivante Apache le serve directement.
La forme de l'URL est :
/<chemin-image>/<mode>/<nomfichier>
où <mode> est :
- un mode défini — la liste vient de
ffMedia::getModes()et de la table<préfixe>showfiles; - ou une taille à la volée sous la forme
<largeur>x<hauteur>(le code reconnaît lexet construit les paramètres lui-même).
Deux événements permettent d'intervenir quand quelque chose manque ou ne va pas, enregistrés dans conf/config.php :
| Événement | Handler | Usage |
|---|---|---|
on_warning | showfiles_on_missing_resource($user_path, $referer, $mode) | ressource manquante : on peut la réaffecter, la remplacer par un visuel de substitution, changer mode |
on_error | showfiles_on_before_parsing_error($strError) | erreur de parsing |
Le handler de projet peut être cms_showfiles_on_warning(), appelé par le handler système.
⚠️
display_errorsdoit rester à0. Un warning imprimé par PHP finit dans le flux binaire de l'image et la corrompt. C'est la raison structurelle pour laquelle le débogage sur cette stack se fait à la demande (?__debug__) et n'est pas « activé en développement ».
Cache des variantes
Les images générées finissent dans cache/, et sont servies avec un Expires long (365 jours). Conséquences :
- si le fichier source change mais pas son nom, l'ancienne variante reste : il faut vider le cache (voir 12) ;
cache/doit être accessible en écriture, et doit être exclu du paquet et des sauvegardes des contenus.
2. Upload
| Point | Quoi |
|---|---|
| Dossier | uploads/ (le dépôt ne contient que uploads/loghi, le reste naît à l'usage). Un PHP ou un script chargé là ne s'exécute pas depuis le navigateur : le .htaccess répond 404 (14 §3) |
| Limite | MAX_UPLOAD dans hook.php — aujourd'hui pratiquement illimité (10000000000000000) : la vraie limite est imposée par upload_max_filesize et post_max_size de PHP. Un site le change en le définissant dans le config |
| Widget | extended_type UploadImage / UploadFile sur les champs des contenus (07 §3) |
| Helpers | library/gallery/common/set_field_uploader.php, get_file_properties.php, get_file_permission.php, fs_operation.php |
Dans hook.php il y a aussi deux helpers pour les fichiers distants :
downloadRemoteFile($url, $destinationDir, $filename); // → tableau avec résultat, mime, extension
saveRemoteImage($url_file, $nome_file, $relative_path);
avec extractMimeType() et mimeToExtension() en complément.
Règle d'hygiène : l'extension d'un upload se décide d'après le MIME vérifié, jamais d'après le nom envoyé par le client. Et le dossier des uploads ne doit pas exécuter de PHP — c'est ce qui sépare un upload d'un webshell.
3. Gestionnaire de fichiers
vendor/wolfgan/filemanager/Filemanager.php avec les services fs_json, fs_php, fs_xml : abstraction pour lire et écrire des structures sur le filesystem. Dans le backend c'est le moteur de l'espace ressources (/restricted/resources).
L'écriture est atomique : Filemanager::save() écrit un fichier temporaire à côté du fichier et le renomme, puis invalide l'OPcache, ainsi une requête concurrente n'inclut jamais un fichier écrit à moitié. Si un fichier PHP est quand même corrompu, fs_php.php le supprime et la lecture renvoie l'erreur au lieu d'arrêter la page : il se refait à l'écriture suivante. read($percorso, $chiavi) ne renvoie que les clés qui existent (une clé absente ne renvoie plus null).
Il y a aussi library/gallery/common/check_fs.php et library/gallery/job.php avec get_check_fs() : vérification récursive des permissions et tailles de l'arborescence des fichiers, utilisée par le diagnostic.
4. Miniatures et images dans les contenus
| Fichier | Rôle |
|---|---|
library/gallery/process/gallery_thumb.php, vgallery_thumb.php | génération des miniatures pour les listes |
library/gallery/common/get_thumb.php | helper de calcul |
ff/classes/ffImage/ | la classe de manipulation d'images du framework |
library/Orientation-Fix-PHP-master/ | correction de l'orientation EXIF |
Le contrôle check_thumb() fait partie du diagnostic (conf/gallery/job/diagnostic/).
5. Ressources statiques
cm/static.php sert /themes, /uploads et /asset (mappés par le kernel). La pipeline de minification et de concaténation utilise library/minify, gminify, cssmin, jsmin ; elle se pilote avec DEBUG_MODE, DISABLE_CACHE et CACHE_LAST_VERSION.
Dans le .htaccess généré par l'installeur il y a aussi les règles pour les sous-domaines media. et static. : si l'on veut servir les médias depuis un hôte séparé (ou depuis library/BunnyCDN/), c'est là. Les installations depuis le ZIP le reçoivent de l'assistant, jc_write_htaccess() dans install/lib.php ; celles faites avec l'ancien installeur, de conf/gallery/install/.htaccess-cms.tpl.
Le sous-domaine media.
media.<domaine>/<chemin> ne lit pas dans uploads/ : il sert la copie dans cache/.thumbs/<chemin>, que ff/classes/ffMedia.php crée (un lien physique pour les originaux, un nouveau fichier pour les versions redimensionnées). Quand la copie manque :
- si l'original avec le même chemin se trouve dans
uploads/, Apache le sert tel quel, y compris par morceaux (Range, dont les vidéos sur iPhone ont besoin) ; - sinon la requête arrive au 404 et à
cm/error.php, qui fait générer la copie parffMedia::process()et répond par une redirection : 302 vers la même adresse, ou 301 vers le nom sous lequel la copie est enregistrée (1000-414/tags/x.jpg→tags/x-1000-414.jpg) ; - si la copie ne peut pas être créée,
process()renvoiefalseet la réponse est un 404.
Le point 1 vaut aussi pour /media/ sur l'hôte principal.
⚠️ Trois façons d'envoyer en 500 les images de
media., toutes vues sur grandchef le 28/9/2026 :
- la règle qui envoie à
index.phples fichiers inexistants vaut aussi pourmedia., parce qu'elle le cite ou parce que la condition sur l'hôte n'est pas ancrée :(www\.x\.com|x\.com)$sans^vaut aussi pourmedia.x.com. La copie manquante rebondit entre/index.phpet/cache/.thumbs/index.phpjusqu'à la limite des 10 redirections internes d'Apache (dans le journal : Request exceeded the limit of 10 internal redirects). Le modèle de l'ancien installeur est ancré ; l'assistant l'est depuis la 1.6.2, avant il écrivait(www\.x\.com|x\.com)$ [NC]dans le bloc# Front controller. Les.htaccessfaits à la main sont à vérifier ;- on vide
cache/.thumbs/:bin/deploy.sh --svuota-cachen'y touche pas, unrm -rf cache/*si ;- le point 1 manque sur un site installé avant le 28/9/2026 : les originaux dont
ffMediane parvient pas à créer la copie (vu avec des JPG et des vidéos) reçoivent un 404, et avant cette date un 301 permanent vers un chemin tronqué (/prodotto-v2/intro.mp4→tto-v2/intro.mp4).
Sites déjà installés. Le .htaccess généré ne se met pas à jour avec le code : le déploiement ne l'envoie pas (14). Dans le bloc #media with SubDomains on ajoute à la main la condition RewriteCond %{REQUEST_URI} !^<FF_SITE_PATH>/uploads/ avant la RewriteRule et, juste après le bloc, les trois lignes de la règle du point 1. On les copie depuis conf/gallery/install/.htaccess-cms.tpl en remplaçant [FF_SITE_PATH] par le chemin du site, vide si le site est à la racine.
Un .htaccess écrit par l'assistant (en tête : generato dal wizard) a des blocs aux noms différents et, s'il est antérieur à la 1.6.2, aussi la condition non ancrée. Dans le bloc # Immagini servite dal sotto-dominio media. va la même condition sur uploads/ ; juste après le bloc, les trois lignes du point 1 ; dans le bloc # Front controller la condition sur l'hôte prend le ^ initial. Le texte exact est celui qu'écrit jc_write_htaccess().
La règle commentée #media:404 goto static est une alternative au point 2 : elle envoie vers le sous-domaine static. au lieu de cm/error.php. Jusqu'au 28/9/2026 elle avait une coquille (^!-f au lieu de !-f) qui l'empêchait de se déclencher.
6. Symptômes et causes fréquentes
| Symptôme | Cause probable |
|---|---|
| L'image sort corrompue ou le navigateur dit « image non valide » | un warning PHP imprimé dans le flux : display_errors n'est pas à 0 |
| La variante ne se met pas à jour après remplacement du fichier | cache des variantes dans cache/, avec Expires à un an |
| 404 sur un mode qui existe | le mode n'est pas dans la liste (ffMedia::getModes() / table showfiles) : utiliser la forme LxH |
| Upload qui échoue sans message | upload_max_filesize/post_max_size de PHP, pas MAX_UPLOAD |
| Images tournées après envoi depuis un téléphone | orientation EXIF non appliquée |
Toutes les images de media. en 500, dans le journal exceeded the limit of 10 internal redirects | copies de cache/.thumbs/ manquantes et règle vers index.php valable aussi pour media. (§5) |
Une image ou une vidéo de media. répond 301 vers une adresse tronquée (tto-v2/…) | ffMedia::process() d'avant le 28/9/2026 sur un original dont il ne parvenait pas à créer la copie : mettre à jour le code et ajouter au .htaccess la règle du §5 |