Importateur d'images et file d'attente

Ce document décrit comment le plugin ADP Car Market Hub télécharge, déduplique et associe les images de véhicules, et comment la file d'attente asynchrone d'images déplace le travail d'image de longue durée hors du chemin d'importation synchrone.

Quand utiliser ce document

Lisez ce document si vous devez :

• Comprendre quelles images se retrouvent dans la médiathèque de WordPress et lesquelles sont réutilisées ou ignorées.
• Diagnostiquer les images de véhicules manquantes, obsolètes ou en double.
• Planifier la conversion WebP ou la capacité de stockage pour un grand catalogue.
• Ajuster le traitement des images en mode cron pour les hébergements lents ou restreints.

Pour le flux d'importation global, voir Import Engine. Pour la planification côté cron, voir Cron Events And Scheduler.

Aperçu

Deux classes partagent la responsabilité de la gestion des images :

• AS24CI\Image_Importer — télécharge une liste d'URL d'images, les convertit éventuellement en WebP, les associe à une publication de véhicule via media_handle_sideload(), et enregistre l'URL source dans les métadonnées postmeta de la pièce jointe pour déduplication.
• AS24CI\Scheduler — possède la file d'attente d'images asynchrone. Le hook de l'exécuteur as24ci_image_queue_process traite les éléments en attente par lots avec son propre verrou temporaire (transient) et son budget de temps.

L'importateur (Import Engine) décide d'importer les images de manière synchrone ou d'en différer la majeure partie dans la file d'attente, en fonction du mode cron de l'exécution en cours.

Source de vérité pour les images

Pour toute pièce jointe importée, le marqueur canonique « d'où cela provient-il ? » est la métadonnée postmeta _as24ci_source_url sur la pièce jointe (attachment). Le plugin utilise ce marqueur pour :

• Dédupliquer les téléchargements — si une pièce jointe avec la même URL source existe déjà, le plugin la réutilise plutôt que de la télécharger à nouveau.
• Reconstruire la liste _as24ci_image_ids du véhicule de manière autoritaire après la fin de l'exécuteur de la file d'attente, en interrogeant les pièces jointes enfants avec cette clé méta.

Deux clés postmeta sur la publication du véhicule suivent les images importées :

• _as24ci_image_ids — tableau d'ID de pièces jointes WordPress qui appartiennent à la galerie de l'importateur.
• _as24ci_images_hash — hachage MD5 de la liste des images sources. Peut contenir la sentinelle 'pending_queue' pendant que des éléments sont encore dans la file d'attente. L'importation suivante traite 'pending_queue' comme une non-correspondance afin que la liste d'images soit toujours réévaluée jusqu'à ce qu'elle soit entièrement importée.

Les pièces jointes de galerie ajoutées manuellement sont suivies séparément dans _as24ci_manual_image_ids et ne sont jamais supprimées par le plugin.

Importation d'images synchrone

Image_Importer::import_images( int $post_id, array $images, string $listing_id ) effectue le travail synchrone :

1. Inclut de manière différée (lazy load) les fichiers d'administration des médias WordPress (wp-admin/includes/media.php, file.php, image.php).
2. Réapplique de manière défensive la capacité as24ci_max_images.
3. Pré-récupère les URL sources connues de la publication en une seule fois via prefetch_known_urls_for_post() pour éviter N requêtes de base de données par image.
4. Pour chaque image (URL sous forme de chaîne ou tableau avec les clés url / src / href / original / imageUrl) : - Réutilise une pièce jointe existante si l'URL source est déjà connue (carte en mémoire d'abord, puis une recherche postmeta _as24ci_source_url). - Sinon, appelle download_url( $url, 30 ) (délai d'attente de 30 secondes), convertit éventuellement en WebP, et appelle media_handle_sideload() pour créer la pièce jointe. - Écrit _as24ci_source_url sur la nouvelle pièce jointe et l'ajoute à la carte de déduplication en mémoire. - Enregistre les échecs (erreurs de téléchargement, erreurs de chargement latéral) dans les journaux et passe à l'image suivante.
5. Fusionne les nouveaux ID de pièces jointes dans _as24ci_image_ids (en préservant les éléments précédemment importés) et définit l'image mise en avant sur la première pièce jointe si la publication n'en a pas déjà une.

Les ID existants sont fusionnés plutôt qu'écrasés afin que les appels de l'exécuteur de file d'attente accumulent les pièces jointes pour la même publication sur plusieurs exécutions.

Conversion WebP

Lorsque as24ci_convert_to_webp est 1, l'importateur tente de convertir chaque image téléchargée en WebP avant le chargement latéral (sideload) :

• La qualité est lue depuis as24ci_webp_quality (valeur par défaut 80 si non définie) et limitée à la plage 1–100. Le filtre as24ci_webp_quality peut remplacer cette valeur.
• La fonction imagewebp() de GD est essayée en premier ; Imagick est utilisé comme solution de secours.
• Si aucune de ces extensions n'est disponible, la conversion est ignorée et l'image d'origine est chargée de manière latérale. Une ligne de journal est émise.
• Si la conversion produit un fichier vide ou échoue, le fichier temporaire est nettoyé et l'image d'origine est utilisée.

Le fichier converti hérite du nom de fichier d'origine avec l'extension remplacée par .webp.

Importation en mode cron (mis en file d'attente)

Lorsque le planificateur exécute une importation (cron ou REST), il définit Importer::set_cron_image_queue( true ) si as24ci_cron_image_queue est 1 (la valeur par défaut). Pour chaque véhicule ayant plus d'une image, l'importateur :

1. Télécharge uniquement la première image immédiatement via le chemin synchrone afin que le véhicule ait une image mise en avant.
2. Vérifie au préalable si toutes les images restantes sont déjà associées (via la carte de déduplication). Si oui, aucune entrée de file d'attente n'est créée et le _as24ci_images_hash final est écrit immédiatement.
3. Sinon, appelle enqueue_remaining_images() pour ajouter des éléments de la forme { post_id, listing_id, url, images_hash } à l'option as24ci_image_queue. Le _as24ci_images_hash du véhicule est défini sur la sentinelle 'pending_queue' afin que les futures importations continuent de réévaluer jusqu'à ce que la file d'attente soit terminée.

La file d'attente est strictement limitée à Scheduler::IMAGE_QUEUE_SIZE_LIMIT éléments. Les nouvelles entrées sont rejetées lorsque la limite est atteinte et une ligne de journal est émise.

Exécuteur de file d'attente (Queue worker)

AS24CI\Scheduler::run_image_queue() est lié au hook cron as24ci_image_queue_process et exécute les téléchargements différés réels :

1. Appelle set_time_limit(300) (sous réserve des restrictions de l'hébergeur).
2. Acquiert le verrou temporaire as24ci_image_queue_running avec la durée de vie (TTL) Scheduler::IMAGE_QUEUE_LOCK_TTL. Un verrou obsolète (plus ancien que la TTL) est automatiquement effacé.
3. Charge la file d'attente depuis l'option as24ci_image_queue.
4. Traite les éléments par lots de Scheduler::IMAGE_QUEUE_BATCH_SIZE tant que la file d'attente n'est pas vide et que le budget de temps (IMAGE_QUEUE_LOCK_TTL − 60s) n'est pas épuisé.
5. Pour chaque élément, appelle Image_Importer::import_images() pour l'unique URL. Les erreurs sont capturées et enregistrées ; l'élément est abandonné pour éviter une boucle de blocage (poison-pill).
6. Conserve la file d'attente restante et écrit les statistiques par exécution dans as24ci_image_queue_last_run ({ processed, failed, remaining, timestamp }).
7. Pour chaque publication entièrement vidée de la file d'attente lors de cette exécution, reconstruit _as24ci_image_ids de manière autoritaire à partir des pièces jointes enfants réelles étiquetées avec _as24ci_source_url et stocke le _as24ci_images_hash final. Cela garantit que les métadonnées sont complètes et cohérentes même si certains éléments de la file d'attente ont échoué.
8. Planifie la prochaine exécution via maybe_schedule_image_queue_worker() s'il reste des éléments.

La valeur images_hash de l'exécuteur est validée pour être une chaîne MD5 minuscule de 32 caractères avant utilisation. Les entrées corrompues sont traitées comme absentes afin que le hachage de la publication ne soit pas finalisé à partir de données erronées.

Référence de configuration

Les valeurs exactes de IMAGE_QUEUE_LOCK_TTL, IMAGE_QUEUE_BATCH_SIZE et IMAGE_QUEUE_SIZE_LIMIT sont définies comme des constantes sur AS24CI\Scheduler et peuvent changer d'une version du plugin à l'autre. Vérifiez-les dans le code source actuel si vous devez planifier une charge spécifique.

Notes opérationnelles

• WP-Cron est le déclencheur par défaut. Sur les sites à faible trafic, envisagez un cron côté serveur / cron système pointant vers wp-cron.php (avec DISABLE_WP_CRON défini sur true) afin que la file d'attente se vide de manière prévisible.
• Les téléchargements d'images sont effectués via download_url() qui utilise l'API HTTP de WordPress. Les hébergeurs qui bloquent le trafic HTTP sortant doivent autoriser les hôtes d'images AutoScout24.
• La déduplication des images est basée sur l'URL source exacte. Les URL qui diffèrent uniquement par la chaîne de requête (query string) ou les paramètres de signature seront traitées comme des sources distinctes et téléchargées séparément.
• Les pièces jointes de galerie manuelles suivies dans _as24ci_manual_image_ids ne sont jamais écrasées ou supprimées par l'importateur ou l'exécuteur de file d'attente.
• L'exécuteur de file d'attente reconstruit _as24ci_image_ids à partir des pièces jointes enfants réelles à la fin de chaque publication entièrement vidée ; si vous manipulez directement les métadonnées entre les exécutions de l'exécuteur, vos modifications risquent d'être annulées.

Dépannage

• Les véhicules apparaissent sans aucune image. Confirmez que as24ci_import_images est activé. Vérifiez que as24ci_max_images n'est pas égal à zéro là où c'est prévu. En mode cron, l'image principale est importée de manière synchrone ; si aucune image n'apparaît du tout, recherchez des erreurs de téléchargement dans le journal du plugin.
• Seule la première image est présente après une importation cron. C'est le comportement attendu lors des importations en mode cron jusqu'à ce que l'exécuteur as24ci_image_queue_process ait terminé son travail. Vérifiez as24ci_image_queue_last_run pour suivre la progression et la taille de la file d'attente.
• La file d'attente grandit mais ne se vide jamais. Vérifiez que WP-Cron est actif (ou qu'un cron serveur déclenche wp-cron.php). Recherchez un verrou temporaire as24ci_image_queue_running bloqué plus ancien que la TTL de l'exécuteur. L'exécuteur efface automatiquement les verrous obsolètes lors de l'exécution suivante.
• La conversion WebP ne se produit pas. Assurez-vous que as24ci_convert_to_webp est 1 et que GD avec le support WebP (imagewebp) ou Imagick est installé. Le plugin consigne la raison dans les journaux lorsque la conversion est ignorée.
• Des images semblant être des doublons apparaissent dans la galerie. La clé de déduplication est l'URL source exacte. Les CDN qui ajoutent des paramètres de requête uniques à chaque requête empêcheront la déduplication. Vérifiez les URL dans le contenu de l'API via la journalisation détaillée.
• Les images ont disparu après la suppression d'un véhicule. Le Vehicle_Deleter supprime les pièces jointes suivies dans _as24ci_image_ids. Les pièces jointes de galerie manuelles (_as24ci_manual_image_ids) sont préservées. Vérifiez quelle liste contenait l'ID de la pièce jointe concernée.

Documents connexes

• Import Engine
• Cron Events And Scheduler
• Data Model
• Database Schema
• Section overview