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

> Récupérer une image externe et l'attacher automatiquement comme image mise en avant, sans jamais passer par l'écran d'import manuel.

- Auteur : Clément Hadrot
- Publié le : 2020-03-09
- Mis à jour le : 2020-03-09
- Catégorie : Tips
- URL : https://wpmoderne.dev.wordpress-developpement.fr/tips/media-sideload-image-image-a-la-une-depuis-url/

## L’essentiel

- Télécharge et attache une image externe en une fonction
- Fonctionne bien pour un import automatisé
- Nécessite quelques fichiers WordPress chargés en amont

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.

> L'essentiel à retenir : Télécharge et attache une image externe en une fonction ; Fonctionne bien pour un import automatisé ; Nécessite quelques fichiers WordPress chargés en amont

## 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.