Sur un site WordPress un peu sérieux, les images ne sont plus de simples fichiers posés dans un dossier. Elles doivent être responsives, rapides à charger, accessibles, faciles à maintenir par l’équipe éditoriale. C’est exactement là que wp_get_attachment_image devient intéressante. Cette fonction WordPress ne se contente pas de renvoyer une URL d’image : elle génère carrément la balise complète, avec srcset, sizes et tous les attributs HTML dont tu as besoin pour un front propre.
Quand on la compare à wp_get_attachment_image_src, on voit vite qu’on ne joue pas dans la même catégorie : l’une renvoie des données brutes, l’autre prépare un HTML prêt à coller dans tes templates. Pour un projet moderne, faire l’impasse dessus revient à se priver gratuitement de performances et de confort de développement.
Dans le développement web WordPress actuel, la vraie question n’est plus « comment afficher une image », mais « comment l’afficher correctement dans un thème ou un builder sans réinventer la roue ». Qu’il s’agisse d’un site vitrine, d’un e‑commerce ou d’un blog média, on se retrouve toujours à jongler entre les tailles natives, les recadrages, les champs ACF, les miniatures d’articles et les images de blocs personnalisés.
Bien utilisée, wp_get_attachment_image simplifie tout ça : elle gère déjà une grosse partie des problèmes de responsive, elle parle parfaitement avec des plugins comme Advanced Custom Fields, et elle respecte la configuration d’images WordPress (tailles intermédiaires, éventuel CDN, sous-domaines médias). Les développeurs qui continuent à injecter des URLs d’images en dur finissent presque toujours par tomber sur un mur de dette technique. Autant poser tout de suite des bases saines.
En bref
- wp_get_attachment_image renvoie une balise <img> complète, avec srcset et sizes, idéale pour les images WordPress responsives.
- wp_get_attachment_image_src renvoie uniquement un tableau avec l’URL d’une taille d’image, sa largeur, sa hauteur et son nom de taille.
- Pour un champ image ACF, le retour en ID est de loin le plus adapté pour exploiter ces deux fonctions proprement.
- La combinaison wp_get_attachment_image + tailles intermédiaires WordPress améliore directement les temps de chargement, surtout sur mobile.
- Choisir l’une ou l’autre fonction dépend du contexte : HTML prêt à l’emploi ou besoin de données brutes pour un traitement sur mesure.
wp_get_attachment_image dans WordPress : mode d’emploi concret et bonnes pratiques
Pour comprendre la fonction wp_get_attachment_image, il faut d’abord la replacer dans le système de médias de WordPress. Quand quelqu’un envoie une image via la médiathèque, le CMS fabrique automatiquement plusieurs tailles intermédiaires : miniature, moyen, grand, et éventuellement des tailles personnalisées déclarées dans le thème.
Depuis WordPress 4.4, ces tailles servent à alimenter le fameux srcset, ce qui permet au navigateur de choisir la bonne résolution selon l’écran. La fonction dont on parle ici vient justement piocher dans ces tailles pour générer un HTML propre.
Sa signature officielle ressemble à ceci : wp_get_attachment_image( $attachment_id, $size, $icon, $attr ). Le premier paramètre, $attachment_id, doit correspondre à un ID d’attachement image, pas à l’ID d’un article ni d’une page. C’est un piège classique : beaucoup de devs passent $post->ID et se demandent pourquoi rien ne s’affiche. Le deuxième paramètre, $size, accepte soit un nom de taille (par exemple « thumbnail », « medium », « large », ou une taille custom), soit un tableau de type array( largeur, hauteur ). Les deux paramètres suivants sont optionnels : $icon indique si l’on souhaite un icône par défaut pour les fichiers non images, et $attr permet d’ajouter ou de surcharger des attributs HTML (class, loading, decoding, etc.).
En pratique, un appel minimaliste peut ressembler à : echo wp_get_attachment_image( $attachment_id, ‘medium’ );. Cette ligne retourne immédiatement une balise <img> complète, avec tout ce qu’il faut pour un affichage standard. On peut ensuite enrichir cet appel au fur et à mesure que le besoin se précise. Par exemple, sur un site e‑commerce, on ajoute souvent une classe CSS pour intégrer l’image dans une grille Bootstrap ou Tailwind, et on force un loading= »lazy » pour soulager le chargement de page. C’est là que le quatrième paramètre prend tout son sens, avec un tableau d’attributs passé à la fonction.
Une erreur fréquente consiste à croire que wp_get_attachment_image va deviner toute seule l’image associée à un article. Ce n’est pas le cas : elle ne sait travailler qu’avec un ID explicite d’attachement. Si tu veux l’image mise en avant d’un article, il faut d’abord récupérer cet ID avec get_post_thumbnail_id( $post->ID ), puis le passer à la fonction. C’est exactement ce qui corrige le cas typique où un dev tente wp_get_attachment_image( 54, array( 300, 300 ) ) avec 54 qui correspond à un post, pas à un media.
Une fois ce mécanisme bien assimilé, wp_get_attachment_image devient un réflexe dès qu’il faut injecter des images WordPress dans les templates. La fonction enlève beaucoup de bruit dans le code : pas besoin de gérer soi-même les tailles, ni de construire des balises <img> à la main. Pour un projet qui va vivre, être repris, refondu, cette simplicité paye toujours à moyen terme.
Paramètres avancés, attributs HTML et petits réglages malins
Une fois que la base est en place, la vraie différence se joue sur le quatrième paramètre. Le tableau $attr donne un contrôle fin sur les attributs de l’image. On peut y passer une classe CSS, un alt personnalisé, un decoding ou un fetchpriority. Par exemple : echo wp_get_attachment_image( $id, ‘large’, false, array( ‘class’ => ‘img-responsive hero’, ‘loading’ => ‘lazy’ ) );. WordPress fusionne ces attributs avec ceux qu’il génère déjà, ce qui permet de garder à la fois les avantages du core (srcset, sizes) et les contraintes du design du site.
Autre usage intéressant : le paramètre $icon. Quand il est à true, la fonction peut renvoyer une icône générique pour les fichiers qui ne sont pas des images (PDF, ZIP, etc.). Sur une médiathèque ou une page listant des documents téléchargeables, ce comportement évite d’avoir du HTML vide ou des arrière-plans cassés. Ce n’est pas la facette la plus connue de la fonction, mais sur un intranet ou un espace client, c’est plutôt pratique.
En parallèle, WordPress ajoute de plus en plus d’attributs automatiquement, comme loading= »lazy » sur certaines versions, ou des valeurs de width et height basées sur les tailles intermédiaires. Si un projet a besoin de reprendre la main sur ces réglages, on peut combiner wp_get_attachment_image avec des filtres comme wp_get_attachment_image_attributes. Certains thèmes poussent même le vice jusqu’à injecter des attributs de tracking ou des classes spécifiques pour des animations, tout en conservant le moteur responsive offert par le core.
En résumé, cette fonction combine une interface simple à l’appel, et une vraie capacité de personnalisation pour ceux qui veulent affiner. Ce mélange convient bien aux équipes où l’on a à la fois des intégrateurs débutants et des développeurs plus expérimentés qui peaufinent le backend.
Comparer wp_get_attachment_image et wp_get_attachment_image_src : quelles différences pratiques ?
Quand on regarde la documentation, wp_get_attachment_image_src paraît très proche de wp_get_attachment_image. Dans les deux cas, on part d’un attachement image et d’une taille souhaitée. Pourtant, les usages ne se recoupent pas. La première différence tient au type de retour : wp_get_attachment_image renvoie une chaîne HTML complète, tandis que wp_get_attachment_image_src renvoie un tableau contenant l’URL, la largeur, la hauteur et éventuellement le nom de taille. L’une sert plutôt aux templates, l’autre plutôt au traitement de données ou à des cas de figure sur mesure.
Dans un thème classique, si l’objectif est simplement d’afficher une image dans une loop ou un bloc personnalisé, wp_get_attachment_image fait gagner un temps fou. Pas besoin d’assembler la balise à la main, ni de se souvenir des attributs requis. À l’inverse, si tu construis un composant en JavaScript qui doit consommer des URLs d’image côté front, ou si tu dois générer une balise
Pour clarifier les différences, un tableau comparatif aide souvent à choisir la bonne fonction WordPress selon le cas de figure.
| Fonction WordPress | Type de retour | Cas d’usage principal | Avantages clés |
|---|---|---|---|
| wp_get_attachment_image | Chaîne HTML (<img> complète) | Templates PHP, blocs personnalisés, intégration rapide | Gère srcset/sizes, alt, width/height, attributs HTML, très peu de code à écrire |
| wp_get_attachment_image_src | Tableau [ URL, largeur, hauteur, bool ] | Logique métier, intégration avec JS, construction de balises sur mesure | Permet un contrôle total sur le HTML généré, pratique pour des systèmes d’images externes |
Un cas typique rencontré sur des projets clients : un design qui impose un
Autre point qui sépare les deux approches : la maintenance. Du côté des templates faciles à lire, un echo wp_get_attachment_image( $id, ‘large’ ) est plus lisible pour quelqu’un qui reprend le projet que trois lignes qui extraient d’abord le tableau issu de wp_get_attachment_image_src, puis construisent la balise. À l’échelle d’un gros thème, cette lisibilité fait vraiment la différence.
Exemples concrets d’utilisation de wp_get_attachment_image_src
Pour ne pas rester dans la théorie, prenons quelques scénarios où wp_get_attachment_image_src a vraiment sa place. Premier scénario : un front React ou Vue couplé à WordPress en mode headless. Dans ce cas, le thème PHP sert surtout d’API, et tu renvoies du JSON à un front séparé. La fonction wp_get_attachment_image_src permet d’enrichir la réponse JSON d’un post avec plusieurs tailles d’images, chacune avec ses dimensions. Le front peut ensuite choisir la taille adaptée au contexte, voire fabriquer un
Deuxième scénario : un système de génération de PDF depuis WordPress. Les librairies PHP qui fabriquent des PDF veulent généralement une URL d’image et ses dimensions. Passer par wp_get_attachment_image_src permet de leur servir directement ce qu’elles attendent, sans devoir parser du HTML. La librairie gère le rendu, WordPress fournit les données brutes. C’est une séparation des rôles plutôt propre.
Troisième scénario : un site qui doit synchroniser ses images avec un service externe (PIM, DAM, ou autre). Dans ce cas, l’URL et les dimensions font partie des métadonnées à envoyer. Là encore, récupérées via wp_get_attachment_image_src, elles se prêtent très bien à un envoi dans une API distante. On n’a aucune raison d’utiliser la balise <img> complète dans ce pipeline.
En résumé, dès que tu construis une interface riche ou un traitement hors du HTML classique, wp_get_attachment_image_src devient un outil quasiment incontournable, pendant que wp_get_attachment_image garde la main sur tout ce qui touche au rendu pur dans les templates.
ACF et wp_get_attachment_image : la combinaison gagnante pour les images dynamiques
Dès qu’un projet WordPress dépasse la simple page d’accueil bricolée, Advanced Custom Fields finit souvent par entrer dans l’équation. Et pour les images WordPress, ACF propose plusieurs formats de retour : URL, tableau ou ID d’attachement. Sur le papier, les trois se défendent. En réalité, pour tirer le meilleur de wp_get_attachment_image et de wp_get_attachment_image_src, le format à privilégier dans la majorité des cas reste « ID de l’objet de retour ». C’est ce choix qui aligne parfaitement ACF sur le cœur de WordPress.
Si le champ renvoie un ID, il devient trivial d’écrire : echo wp_get_attachment_image( get_field( ‘mon_image’ ), ‘large’ );. Une seule ligne suffit pour afficher une image responsive, avec tout le bénéfice des tailles intermédiaires et de srcset. En choisissant le retour tableau, on se retrouve déjà à extraire $image[‘ID’] pour repasser cet ID à la fonction. Ce n’est pas dramatique, mais moins fluide à lire. Quant au retour URL, il casse purement et simplement l’intérêt des fonctions d’attachement : impossible d’appeler wp_get_attachment_image ou wp_get_attachment_image_src avec une simple URL, puisqu’elles attendent un ID.
Sur un site corporate classique, cette différence de réglage dans ACF crée à la longue deux catégories de projets : les thèmes où les images sont gérées nativement, faciles à faire évoluer, et ceux où chaque nouveau besoin d’image se transforme en patch spécifique. Les premiers bénéficient pleinement des évolutions du core WordPress (nouvelles tailles, nouveaux attributs, meilleurs comportements de lazy loading). Les seconds restent coincés dans un monde où tout est câblé en dur.
Étude de cas : du champ image ACF à la grille responsive propre
Imaginons un client, appelons-le « Studio Orion », qui veut une page « Équipe » avec des portraits, des rôles et des bios. Le designer prévoit une grille responsive avec deux colonnes sur desktop, une sur mobile, et des portraits recadrés en format carré. Côté backend, ACF fournit un groupe de champs pour chaque membre : nom, fonction, photo, réseaux sociaux. En choisissant « ID » comme format de retour pour la photo, le template peut ressembler à quelque chose comme : echo wp_get_attachment_image( get_sub_field( ‘photo’ ), ‘portrait-carre’, false, array( ‘class’ => ‘membre-photo’ ) );.
Le thème déclare au préalable une taille d’image portrait-carre, par exemple 600×600, recadrée. WordPress fabrique alors les versions adaptées, génère automatiquement le srcset, et wp_get_attachment_image se charge de renvoyer le HTML prêt à poser dans la grille. Si dans un an, le client veut une grille plus grande, ou un design retravaillé, il suffit d’ajuster la taille intermédiaire déclarée dans le thème. Les templates, eux, restent quasiment inchangés.
Dans la même configuration, si ACF avait été réglé sur « URL », il aurait fallu recourir à des fonctions moins propres, voire à des manipulations d’images côté front pour compenser. Pas très agréable à maintenir, surtout quand l’équipe éditoriale commence à envoyer des images de toutes tailles.
Cette articulation propre entre ACF, attachement image et fonctions WordPress dédiées crée un socle solide pour les projets qui grandissent. On peut multiplier les types de contenus, les blocs personnalisés, les carrousels, sans que la gestion des images parte en vrille.
Performance, responsive et SEO : ce que wp_get_attachment_image change réellement
Derrière le débat un peu technique entre wp_get_attachment_image et wp_get_attachment_image_src, il y a un sujet central : la performance. Depuis que les navigateurs comprennent srcset et sizes, le plus gros gain se fait souvent simplement en envoyant une image moins lourde aux mobiles, sans sacrifier trop de qualité. La fonction wp_get_attachment_image profite pleinement de ce mécanisme, en exploitant le système de tailles intermédiaires de WordPress sans effort supplémentaire.
Pour un site qui vit de son trafic organique, ces optimisations ne sont pas un luxe. Les signaux de performance utilisés par les moteurs de recherche prennent en compte le poids des médias, notamment sur les connexions faibles. S’appuyer sur la mécanique native plutôt que sur un bricolage d’URL statiques devient rapidement un avantage. Dans les audits techniques sérieux, on repère vite les thèmes qui respectent ces standards : ils font systématiquement appel à wp_get_attachment_image pour tout ce qui est image éditoriale.
Côté SEO, un autre point entre en jeu : la gestion des attributs alt et des dimensions. La fonction récupère déjà une bonne partie des informations depuis l’attachement lui-même. Si l’équipe éditoriale remplit correctement les champs « Texte alternatif » dans la médiathèque, ces valeurs se retrouvent dans le HTML généré. On n’a donc pas besoin de ressaisir à chaque fois le même contenu dans les templates. En combinant ça avec des hooks ou un peu de logique conditionnelle, on peut même garantir des attributs alt pertinents sur l’ensemble du site, sans finir avec un front rempli de « image123.jpg ».
Quand il vaut mieux ne pas tout déléguer à wp_get_attachment_image
Il existe malgré tout des situations où s’en remettre uniquement à wp_get_attachment_image n’est pas une bonne idée. Les systèmes de CDN d’images avancés qui gèrent eux-mêmes les transformations (recadrage, format AVIF, compression adaptative) demandent souvent de contrôler très finement les URLs générées. Dans ce genre de configuration, tu peux te retrouver à préférer wp_get_attachment_image_src ou même des fonctions maison qui transforment l’URL d’origine en URL dédiée au CDN.
Autre cas : les architectures headless pures où WordPress ne sert que d’API, et où le front est intégralement géré par un framework moderne. Là, la fonction qui renvoie une balise <img> complète perd une partie de son intérêt. Elle reste utile pour des rendus côté serveur, mais beaucoup moins pour un client lourd qui veut garder la main sur la structure du DOM.
L’important, au fond, reste d’identifier clairement dans un projet lesquelles de tes images sont « simples », purement éditoriales, et lesquelles relèvent d’une logique plus avancée. Pour les premières, wp_get_attachment_image fait le job sans discussion. Pour les secondes, wp_get_attachment_image_src – voire un autre système – peut s’imposer, tant que les choix sont cohérents à l’échelle de l’application.
Pièges classiques et erreurs fréquentes avec wp_get_attachment_image
Dans les revues de code, les bugs liés aux images WordPress reviennent toujours aux mêmes endroits. Premier classique : confondre ID de post et ID d’attachement. Comme dans l’exemple très ancien qui traîne sur les forums, quelqu’un teste wp_get_attachment_image( 54, array( 300, 300 ) ) en croyant cibler une image, alors que 54 correspond à un post de type « post ». Résultat : rien ne s’affiche. La solution consiste à récupérer d’abord l’ID de la miniature de l’article avec get_post_thumbnail_id( 54 ), puis de passer ce nouvel ID à la fonction.
Autre piège : utiliser get_the_ID() directement comme premier paramètre, sans vérifier que le post courant est bien un attachement. Certains snippets montrent wp_get_attachment_image( get_the_ID(), ‘medium’ ) sans contexte, ce qui fonctionne uniquement dans une boucle dédiée aux pièces jointes. Dans une loop classique d’articles, ça ne renverra rien de cohérent. Le bon réflexe reste de toujours se demander : « l’ID que je passe correspond-il vraiment à un média uploadé dans la médiathèque ? ».
Il y a aussi les cas où l’on attend un redimensionnement magique alors que WordPress ne dispose tout simplement pas de la taille demandée. Si on passe un tableau de type array( 700, 600 ), WordPress va chercher la taille intermédiaire la plus proche. Mais si aucune ne correspond, il peut renvoyer l’originale ou une version mal adaptée. Pour éviter ce genre de surprise, mieux vaut déclarer des tailles nommées et les cibler explicitement dans la fonction, plutôt que d’empiler des tableaux de dimensions dans tout le code.
Checklist minimale avant d’utiliser wp_get_attachment_image en production
Pour éviter les mauvaises surprises, quelques points méritent d’être vérifiés avant de généraliser la fonction dans un thème ou un plugin :
- Vérifier l’origine de l’ID : s’assurer qu’il s’agit bien d’un attachement image stocké dans la médiathèque.
- Déclarer proprement les tailles intermédiaires : utiliser des noms explicites et les documenter (par exemple « card-thumb », « hero-large »).
- Tester le comportement sur mobile : inspecter le srcset généré, vérifier les poids d’images réellement chargées.
- Soigner les alt dans la médiathèque : profiter du fait que la fonction les récupère automatiquement.
- Standardiser les réglages ACF : imposer le retour en ID pour les champs image, sauf exception bien justifiée.
Avec cette base solide, la différence entre wp_get_attachment_image et wp_get_attachment_image_src devient presque une question de style de développement plus qu’un casse-tête. On sait quand on veut du HTML prêt à l’emploi, et quand on a besoin de données brutes pour construire autre chose autour.
Quand utiliser wp_get_attachment_image plutôt que wp_get_attachment_image_src ?
Utilise wp_get_attachment_image dès que ton objectif est d’afficher une image dans un template PHP ou un bloc personnalisé, sans logique complexe autour. La fonction renvoie une balise complète avec srcset, sizes, alt et dimensions. Passe à wp_get_attachment_image_src si tu as besoin uniquement des données d’image (URL, largeur, hauteur) pour les exploiter dans un front JavaScript, un PDF, un service externe ou un composant HTML sur mesure.
Pourquoi mon appel wp_get_attachment_image ne renvoie rien ?
La cause la plus fréquente est l’utilisation d’un mauvais ID. La fonction attend un ID d’attachement image, pas l’ID d’un post ou d’une page. Vérifie que tu passes bien get_post_thumbnail_id( $post->ID ) pour une image mise en avant, ou un ID de média issu d’un champ ACF configuré en retour ‘ID’. Autre possibilité : la taille demandée n’existe pas et WordPress ne trouve pas de version adaptée.
Quel format de retour choisir pour un champ image ACF ?
Pour tirer le meilleur des fonctions d’image WordPress, le format de retour ‘ID de l’objet’ est généralement le plus pertinent. Il permet d’appeler directement wp_get_attachment_image ou wp_get_attachment_image_src, de profiter des tailles intermédiaires, de srcset et de la récupération automatique du texte alternatif. Le retour ‘URL’ est à réserver à des cas très spécifiques où tu ne comptes pas utiliser les fonctions natives d’attachement.
Comment ajouter des classes personnalisées à l’image générée ?
Passe un tableau d’attributs en quatrième paramètre de wp_get_attachment_image, par exemple : echo wp_get_attachment_image( $id, ‘large’, false, array( ‘class’ => ‘img-fluid card-img’, ‘loading’ => ‘lazy’ ) ). WordPress fusionnera ces attributs avec ceux qu’il génère déjà. Tu peux aussi utiliser le filtre wp_get_attachment_image_attributes si tu dois appliquer une logique globale à tout le site.
wp_get_attachment_image est-elle suffisante pour gérer un CDN d’images ?
Pour un CDN basique branché sur les URLs médias par défaut de WordPress, wp_get_attachment_image suffit, car elle respecte les réglages du site et renvoie des URLs déjà réécrites par le CDN. Pour des CDN plus avancés qui nécessitent des paramètres spécifiques dans les URLs (qualité, recadrage, format AVIF, etc.), il est parfois plus adapté de partir de wp_get_attachment_image_src ou de l’URL brute, puis de générer manuellement les liens vers le CDN selon tes règles.
