Guide produit
Connecteur médias imgproxy
Répliquer la médiathèque vers un stockage S3 et servir des URL imgproxy signées, avec profils nommés, formats modernes et repli local.
- Version publiée
- 0.5.4
- Compatibilités
- WordPress 6.3 minimum · 6.8.8, 7.0.4 et 7.1 recettés · PHP 8.2 à 8.4 recettés · imgproxy 4.0.3 · MinIO S3 recetté
- Fiche produit
- Connecteur médias imgproxy
Prérequis
Le connecteur fonctionne sans compte et sans service Novelience : aucune clé d’activation n’est demandée, aucune vérification de licence n’est effectuée et aucun appel n’est émis vers un serveur de Novelience. Les seules connexions sortantes vont vers les services que vous désignez et administrez, votre stockage compatible S3 et votre serveur imgproxy ; leurs identifiants ne quittent pas votre site. Une version installée continue de fonctionner à l’identique si votre abonnement prend fin ; l’abonnement ouvre le support et l’accès aux nouvelles versions.
| Composant | Versions recettées |
|---|---|
| WordPress | 6.3 minimum · 6.8.8, 7.0.4 et 7.1 recettés |
| PHP | 8.2 minimum · 8.2, 8.3 et 8.4 recettés |
| imgproxy | 4.0.3 recetté ; toute version 4.x configurée avec IMGPROXY_KEY, IMGPROXY_SALT et l’accès S3 (IMGPROXY_USE_S3=true et ses identifiants) |
| Stockage objet | Compatible S3 en adressage par chemin : MinIO recetté ; AWS S3, Scaleway, OVHcloud et équivalents |
| Réseau | WordPress doit joindre le point d’accès S3 en sortie ; les visiteurs doivent joindre l’URL publique imgproxy, et WordPress aussi pour que le diagnostic aboutisse |
| Droits | Un compte administrateur pour installer ; manage_options pour ouvrir Réglages › Médias imgproxy, enregistrer la connexion et lancer le test. Le connecteur n’expose aucun filtre sur cette capacité. |
Installation
- Téléchargez l’archive depuis Espace client › Mes produits et licences, puis vérifiez son empreinte SHA-256 avec celle affichée (sous Linux ou macOS : sha256sum imgproxy-media-connector-0.5.4.zip).
- Dans WordPress, ouvrez Extensions › Ajouter › Téléverser une extension, sélectionnez l’archive et cliquez sur Installer.
- Activez l’extension. Le connecteur ne crée aucune table : ses réglages vivent dans les options de WordPress et la clé d’objet de chaque média dans les métadonnées de la médiathèque. L’activation n’affiche donc aucun message relatif à la base de données.
- Ouvrez Réglages › Médias imgproxy, renseignez la connexion puis lancez « Tester la connexion ». Tant que la configuration est incomplète, rien n’est répliqué et les URL locales continuent d’être servies.
- Affectez la licence au site dans votre espace client (Réaffecter ce droit) : c’est ce qui ouvre le support et les mises à jour pour ce site.
Configuration
- Ouvrez Réglages › Médias imgproxy.
- Renseignez la connexion : point d’accès du stockage, bucket, région, clé d’accès, clé secrète ; puis l’URL publique imgproxy, sa clé et son sel en hexadécimal, identiques aux valeurs du serveur imgproxy. Une région laissée vide vaut us-east-1 ; elle doit correspondre à celle du bucket, car elle entre dans la signature. L’URL publique imgproxy peut être relative si un serveur mandataire la sert sous le même domaine.
- Choisissez le format par défaut (auto laisse imgproxy négocier WebP ou AVIF avec le navigateur ; webp, avif, jpg ou png forcent le format) et la qualité par défaut (0 conserve celle du serveur).
- Créez des profils nommés (largeur, hauteur, mode fit, fill, fill-down ou force, format, qualité) et associez-les aux tailles d’image enregistrées, y compris full. Le nom est réduit aux lettres et aux chiffres, largeur et hauteur sont bornées à 8 192 pixels et la qualité à 100 ; un profil sans nom, en double, ou dont la largeur et la hauteur sont toutes deux nulles est ignoré.
- Les tailles intermédiaires non associées gardent les dimensions calculées par WordPress ; sans profil associé à full, l’image complète est servie redimensionnée dans une boîte de 1920 × 1920 pixels, sans agrandissement des images plus petites, aussi bien pour le lien direct vers le fichier que pour l’image rendue dans une page. Pour servir l’original à sa taille réelle, associez à full un profil aux dimensions voulues, ou portez cette borne à zéro avec le filtre imgproxy_media_connector_full_size_bound.
- Cliquez sur « Tester la connexion » : le diagnostic écrit un objet de test dans le bucket, demande une URL signée à imgproxy puis supprime l’objet. La bannière n’est verte que si le stockage et imgproxy ont tous deux répondu ; si le stockage échoue, imgproxy n’est pas testé.
Sur un serveur que vous administrez, préférez les constantes dans wp-config.php ou les variables d’environnement : elles priment sur les réglages enregistrés et l’écran les affiche verrouillées.
define('IMGPROXY_STORAGE_ENDPOINT', 'https://s3.exemple.net');
define('IMGPROXY_STORAGE_BUCKET', 'medias');
define('IMGPROXY_STORAGE_REGION', 'fr-par');
define('IMGPROXY_STORAGE_ACCESS_KEY', '…');
define('IMGPROXY_STORAGE_SECRET_KEY', '…');
define('IMGPROXY_PUBLIC_URL', 'https://img.exemple.fr');
define('IMGPROXY_KEY', '…hexadécimal…');
define('IMGPROXY_SALT', '…hexadécimal…');Utilisation
- Chaque image téléversée est répliquée (original et variantes) sous la clé uploads/… du bucket ; les documents non image ne sont jamais concernés.
- Toutes les URL d’image rendues par WordPress (image complète, tailles enregistrées, srcset responsive) deviennent des URL imgproxy signées de la forme <URL publique imgproxy>/<signature>/rs:mode:l:h/q:qualité/f:format/plain/s3://bucket/clé. Les segments rs:, q: et f: ne sont présents que lorsqu’ils s’appliquent : avec les réglages par défaut, format auto et qualité 0, il ne reste que rs:.
- Les variantes sont répliquées pour rester disponibles à vos propres outils, mais les URL servies dérivent toujours de l’original : c’est imgproxy qui redimensionne. Pour limiter le volume stocké, réduisez les tailles générées par WordPress.
- Tant que la configuration est incomplète, les URL locales d’origine sont servies : activer le connecteur ne change rien à l’affichage.
- La clé d’objet n’est enregistrée sur un média qu’une fois son original réellement déposé dans le stockage : un envoi qui échoue laisse le média servi depuis WordPress. Surveillez l’action imgproxy_media_connector_upload_failed et relancez la réplication des médias concernés après un incident de stockage.
- Les images de plus de 25 Mio (26 214 400 octets) ne sont pas répliquées et restent servies depuis WordPress ; relevez cette borne avec le filtre imgproxy_media_connector_max_upload_bytes si vos médias la dépassent.
- Une image retouchée dans l’éditeur de la médiathèque (rotation, recadrage) est renvoyée au stockage à l’enregistrement de la retouche.
- Supprimer un média dans WordPress supprime les objets répliqués ; les fichiers locaux ne sont jamais effacés par le connecteur.
- Les images téléversées avant l’installation sont répliquées à leur prochaine régénération de miniatures (par exemple avec wp media regenerate).
Points d’extension
| Crochet | Rôle |
|---|---|
| imgproxy_media_connector_config | Dernier mot sur chaque valeur de configuration. |
| imgproxy_media_connector_profiles · imgproxy_media_connector_size_profiles | Profils et associations de tailles définis par code. |
| imgproxy_media_connector_should_mirror · imgproxy_media_connector_object_key | Éligibilité d’un média et clé d’objet. |
| imgproxy_media_connector_processing_path · imgproxy_media_connector_signed_url | Chemin de traitement et URL finale. |
| imgproxy_media_connector_full_size_bound · imgproxy_media_connector_attachment_url | Borne de l’image complète (1 920 pixels par défaut, 0 pour servir l’original) et adresse finale du lien direct vers le fichier. |
| imgproxy_media_connector_s3_request_args · imgproxy_media_connector_s3_response · imgproxy_media_connector_max_upload_bytes | Arguments des requêtes vers le stockage, observation de leur réponse et limite de taille (25 Mio par défaut). |
| imgproxy_media_connector_original_uploaded · …_variant_uploaded · …_upload_failed · …_object_deleted | Actions de cycle de vie. |
Limites et sécurité
- Le format auto dépend des options serveur IMGPROXY_AUTO_WEBP ou IMGPROXY_AUTO_AVIF ; sans elles, l’original est servi.
- Les secrets saisis dans l’écran sont stockés en clair dans la table des options WordPress ; les constantes restent la méthode recommandée.
- Le connecteur signe les URL ; il n’active pas la limitation de dimensions côté serveur, à configurer dans imgproxy (IMGPROXY_MAX_SRC_RESOLUTION, etc.).
- Une fois la configuration complète, la disponibilité des images dépend de votre serveur imgproxy : le connecteur ne teste pas sa présence au moment du rendu et ne revient pas aux fichiers locaux. Un serveur imgproxy arrêté ou en erreur rend les images indisponibles jusqu’à son rétablissement, ou jusqu’à la désactivation de l’extension, qui restitue immédiatement les adresses locales. Prévoyez supervision et redondance de ce service.
- Les tailles recadrées sont rendues par imgproxy avec un recadrage centré : une taille enregistrée avec une position de recadrage particulière n’est pas reproduite à l’identique. Utilisez un profil nommé pour maîtriser le résultat.
- Le connecteur est prévu pour une installation autonome. Sur un réseau multisite partageant un même bucket, distinguez les sites avec le filtre imgproxy_media_connector_object_key.
- Le connecteur n’ajoute aucune commande WP-CLI : tout se fait depuis l’écran de réglages.
Désinstaller depuis Extensions › Supprimer retire les réglages et les métadonnées de réplication ; les objets répliqués restent dans votre stockage. Désactiver sans supprimer conserve tout.
Journal des versions
| Version | Changements |
|---|---|
| 0.5.4 | Une valeur négative de réglage n’est plus transformée en sa valeur absolue : la borne basse qui la suit s’applique enfin. Une qualité ou une dimension négative était enregistrée comme une valeur positive plausible. |
| 0.5.3 | Un média dont l’original n’a pas pu être stocké garde son adresse locale au lieu de désigner un objet absent. Les images retouchées dans la médiathèque repartent au stockage. La borne de l’image complète s’applique désormais au lien direct vers le fichier comme à l’image rendue dans une page, qui différaient. L’extension n’interroge plus le répertoire WordPress.org pour ses mises à jour. |
| 0.5.2 | Borne de l’image complète rendue réglable par filtre ; une borne nulle sert l’original à ses dimensions d’origine. |
| 0.5.1 | Fichier d’identité du produit ajouté dans l’archive : nom commercial, référence, version livrée et socles requis. |
| 0.5.0 | Écran Réglages › Médias imgproxy avec constantes verrouillées, secrets enregistrés et diagnostic ; profils nommés et association aux tailles ; format et qualité par défaut (options f: et q:) ; traduction française ; désinstallation propre. |
| 0.4.0 | Version initiale publiée (constantes uniquement), retirée de la distribution le 6 septembre 2026. |
- Un e-mail vous prévient à chaque nouvelle version ; l’archive et son empreinte sont dans Espace client › Mes produits et licences.
- Téléversez la nouvelle archive dans Extensions › Ajouter › Téléverser une extension et confirmez le remplacement de la version installée. Les données et réglages sont conservés ; les migrations de schéma s’exécutent au premier chargement.
- Après une mise à jour, contrôlez le journal des versions ci-dessous : il indique les changements de comportement à vérifier.
Support