media_sideload_image : définir une image à la une depuis une simple URL distante

Un client qui importe des offres d’emploi depuis une API externe nous a demandé, un peu inquiet, comment associer automatiquement le logo de l’entreprise partenaire à chaque annonce publiée. Les logos arrivaient sous forme d’URL brute dans la réponse JSON de l’API, sans jamais transiter par la médiathèque WordPress.

La tentation classique est d’écrire soi-même le téléchargement avec wp_remote_get(), puis de gérer manuellement l’upload, l’attachement et la génération des métadonnées. C’est un travail que WordPress sait déjà faire via la fonction media_sideload_image(), historiquement pensée pour ce cas précis.

Pourquoi cette fonction n’est pas chargée par défaut

media_sideload_image() vit dans wp-admin/includes/media.php, un fichier qui n’est chargé que dans le contexte de l’administration. Sur un import déclenché en front, via une tâche cron ou un endpoint REST personnalisé, il faut donc l’inclure manuellement avant de pouvoir l’appeler, avec ses fichiers compagnons :

if ( ! function_exists( 'media_sideload_image' ) ) {
    require_once ABSPATH . 'wp-admin/includes/media.php';
    require_once ABSPATH . 'wp-admin/includes/file.php';
    require_once ABSPATH . 'wp-admin/includes/image.php';
}

Ces trois fichiers apportent respectivement la fonction de téléchargement, la gestion du système de fichiers WordPress et la génération des différentes tailles d’image.

Attacher l’image comme image à la une

Depuis WordPress 4.8, media_sideload_image() accepte un quatrième paramètre $return_type valant 'id', qui renvoie directement l’identifiant de la pièce jointe plutôt qu’une balise HTML ou une URL. C’est ce format qu’il faut utiliser pour appeler ensuite set_post_thumbnail() :

function of_definir_logo_a_la_une( $post_id, $url_logo ) {
    if ( ! function_exists( 'media_sideload_image' ) ) {
        require_once ABSPATH . 'wp-admin/includes/media.php';
        require_once ABSPATH . 'wp-admin/includes/file.php';
        require_once ABSPATH . 'wp-admin/includes/image.php';
    }

    $attachment_id = media_sideload_image( $url_logo, $post_id, 'Logo partenaire', 'id' );

    if ( is_wp_error( $attachment_id ) ) {
        error_log( 'Import logo échoué pour l\'offre ' . $post_id . ' : ' . $attachment_id->get_error_message() );
        return false;
    }

    set_post_thumbnail( $post_id, $attachment_id );
    return true;
}

Le deuxième paramètre, l’identifiant du post, sert uniquement à renseigner le champ post_parent de la pièce jointe dans la médiathèque, pour garder une trace de l’origine de l’import.

Gérer les échecs proprement

Une API tierce n’est jamais fiable à cent pour cent : logo supprimé côté partenaire, délai de réponse trop long, format d’image non supporté. media_sideload_image() renvoie un objet WP_Error dans tous ces cas, qu’il faut systématiquement vérifier avec is_wp_error() avant d’aller plus loin.

• Prévoir une image de remplacement neutre plutôt que de laisser l’annonce sans image à la une.
• Journaliser l’échec avec l’URL d’origine, pour pouvoir relancer l’import manuellement plus tard.
• Éviter de bloquer tout le processus d’import pour un seul logo manquant.

Éviter les doublons dans la médiathèque

Chaque appel à media_sideload_image() crée une nouvelle pièce jointe, même si l’image a déjà été importée pour une annonce précédente du même partenaire. Sur un flux régulier, cela remplit rapidement la médiathèque d’images identiques. Une vérification par hachage du contenu, ou plus simplement par le stockage de l’URL d’origine dans une meta de la pièce jointe, permet de réutiliser un identifiant existant :

$existant = get_posts( array(
    'post_type'   => 'attachment',
    'meta_key'    => '_url_origine_logo',
    'meta_value'  => $url_logo,
    'numberposts' => 1,
) );

if ( ! empty( $existant ) ) {
    set_post_thumbnail( $post_id, $existant[0]->ID );
    return true;
}

Sur un import récurrent, cette vérification préalable coûte une requête de plus mais évite des centaines de doublons au bout de quelques mois d’exécution automatique.

En résumé

media_sideload_image() reste la manière la plus directe d’attacher une image distante à un contenu WordPress, à condition de charger les bons fichiers d’administration et de traiter les erreurs sans faire planter tout l’import. Elle ne remplace pas un vrai contrôle des tailles générées après coup, qui relève d’un traitement distinct une fois les images en place.