Aller au contenu
JoeCMS Télécharger 3.1.5
Manuel · 11

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 le x et 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énementHandlerUsage
on_warningshowfiles_on_missing_resource($user_path, $referer, $mode)ressource manquante : on peut la réaffecter, la remplacer par un visuel de substitution, changer mode
on_errorshowfiles_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_errors doit 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

PointQuoi
Dossieruploads/ (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)
LimiteMAX_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
Widgetextended_type UploadImage / UploadFile sur les champs des contenus (07 §3)
Helperslibrary/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

FichierRôle
library/gallery/process/gallery_thumb.php, vgallery_thumb.phpgénération des miniatures pour les listes
library/gallery/common/get_thumb.phphelper 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 :

  1. 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) ;
  2. sinon la requête arrive au 404 et à cm/error.php, qui fait générer la copie par ffMedia::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) ;
  3. si la copie ne peut pas être créée, process() renvoie false et 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.php les fichiers inexistants vaut aussi pour media., 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 pour media.x.com. La copie manquante rebondit entre /index.php et /cache/.thumbs/index.php jusqu'à 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 .htaccess faits à la main sont à vérifier ;
  • on vide cache/.thumbs/ : bin/deploy.sh --svuota-cache n'y touche pas, un rm -rf cache/* si ;
  • le point 1 manque sur un site installé avant le 28/9/2026 : les originaux dont ffMedia ne 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ômeCause 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 fichiercache des variantes dans cache/, avec Expires à un an
404 sur un mode qui existele mode n'est pas dans la liste (ffMedia::getModes() / table showfiles) : utiliser la forme LxH
Upload qui échoue sans messageupload_max_filesize/post_max_size de PHP, pas MAX_UPLOAD
Images tournées après envoi depuis un téléphoneorientation EXIF non appliquée
Toutes les images de media. en 500, dans le journal exceeded the limit of 10 internal redirectscopies 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