Afbeeldingen-importer en wachtrij

Dit document beschrijft hoe de ADP Car Market Hub-plugin voertuigafbeeldingen downloadt, ontdubbelt en koppelt, en hoe de asynchrone afbeeldingenwachtrij langdurige afbeeldingstaken buiten het synchrone importtraject houdt.

Wanneer u dit document moet gebruiken

Lees dit document als u het volgende wilt doen:

• Begrijpen welke afbeeldingen in de WordPress Media Library terechtkomen en welke worden hergebruikt of overgeslagen.
• Ontbrekende, verouderde of dubbele voertuigafbeeldingen diagnosticeren.
• WebP-conversie of opslagcapaciteit plannen voor een grote catalogus.
• De verwerking van afbeeldingen in cron-modus afstemmen op trage of beperkte hosting.

Zie Import Engine voor de omliggende importstroom. Zie Cron Events And Scheduler voor de planning aan de cron-zijde.

Overzicht

Twee klassen delen de verantwoordelijkheid voor de verwerking van afbeeldingen:

• AS24CI\Image_Importer — downloadt een lijst met afbeeldings-URL's, converteert deze optioneel naar WebP, koppelt ze aan een voertuigbericht via media_handle_sideload() en registreert de bron-URL in de attachment-postmeta voor ontdubbeling.
• AS24CI\Scheduler — is eigenaar van de asynchrone afbeeldingenwachtrij. De worker-hook as24ci_image_queue_process verwerkt openstaande items in batches met een eigen tijdelijke vergrendeling (transient lock) en tijdsbudget.

De importer (Import Engine) beslist of afbeeldingen synchroon worden geïmporteerd of dat het merendeel ervan naar de wachtrij wordt uitgesteld, op basis van de cron-modus van de huidige run.

Bron van waarheid voor afbeeldingen

Voor elk geïmporteerd bijlagebestand is de canonieke markering "waar komt dit vandaan?" de _as24ci_source_url-postmeta op het bijlage-bericht (attachment post). De plugin gebruikt deze markering om:

• Downloads te ontdubbelen — als er al een bijlage met dezelfde bron-URL bestaat, hergebruikt de plugin deze in plaats van deze opnieuw te downloaden.
• De _as24ci_image_ids-lijst van het voertuig op gezaghebbende wijze opnieuw op te bouwen nadat de wachtrij-worker klaar is, door onderliggende bijlagen met deze metasleutel op te vragen.

Twee postmeta-sleutels op het voertuig-bericht volgen geïmporteerde afbeeldingen:

• _as24ci_image_ids — array van WordPress-bijlage-ID's die behoren tot de galerij van de importer.
• _as24ci_images_hash — MD5-hash van de bronafbeeldingenlijst. Kan de sentinel 'pending_queue' bevatten zolang er nog items in de wachtrij staan. De volgende import behandelt 'pending_queue' als een mismatch, zodat de afbeeldingenlijst altijd opnieuw wordt geëvalueerd totdat deze volledig is geïmporteerd.

Handmatig toegevoegde galerijbijlagen worden apart bijgehouden in _as24ci_manual_image_ids en worden nooit door de plugin verwijderd.

Synchrone afbeeldingenimport

Image_Importer::import_images( int $post_id, array $images, string $listing_id ) voert het synchrone werk uit:

1. Laadt op luie wijze (lazy load) de WordPress-mediabeheerbestanden (wp-admin/includes/media.php, file.php, image.php).
2. Past defensief de as24ci_max_images-limiet opnieuw toe.
3. Haalt de bekende bron-URL's van het bericht eenmalig vooraf op via prefetch_known_urls_for_post() om N afzonderlijke databasequery's per afbeelding te voorkomen.
4. Voor elke afbeelding (tekenreeks-URL of array met de sleutels url / src / href / original / imageUrl): - Hergebruikt een bestaande bijlage als de bron-URL al bekend is (eerst in-memory map, daarna een _as24ci_source_url-postmeta-zoekopdracht). - Roept anders download_url( $url, 30 ) aan (time-out van 30 seconden), converteert optioneel naar WebP en roept media_handle_sideload() aan om de bijlage te maken. - Schrijft _as24ci_source_url op de nieuwe bijlage en voegt deze toe aan de in-memory ontdubbelingsmap. - Logt fouten (downloadfouten, sideloadfouten) en gaat door naar de volgende afbeelding.
5. Voegt de nieuwe bijlage-ID's samen in _as24ci_image_ids (waarbij eerder geïmporteerde items behouden blijven) en stelt de uitgelichte afbeelding (post thumbnail) in op de eerste bijlage als het bericht er nog geen heeft.

Bestaande ID's worden samengevoegd in plaats van overschreven, zodat aanroepen van de wachtrij-worker bijlagen voor hetzelfde bericht over meerdere runs verzamelen.

WebP-conversie

Wanneer as24ci_convert_to_webp op 1 staat, probeert de importer elke gedownloade afbeelding naar WebP te converteren voordat deze via sideloading wordt toegevoegd:

• De kwaliteit wordt gelezen uit as24ci_webp_quality (standaard 80 indien niet ingesteld) en begrensd tot het bereik 1–100. Het filter as24ci_webp_quality kan de waarde overschrijven.
• GD's imagewebp() wordt eerst geprobeerd; Imagick wordt gebruikt als fallback.
• Als geen van beide extensies beschikbaar is, wordt de conversie overgeslagen en wordt de originele afbeelding via sideloading toegevoegd. Er wordt een logregel gegenereerd.
• Als de conversie een leeg bestand oplevert of mislukt, wordt het tijdelijke bestand opgeschoond en wordt de originele afbeelding gebruikt.

Het geconverteerde bestand erft de originele bestandsnaam waarbij de extensie is vervangen door .webp.

Import in cron-modus (wachtrij)

Wanneer de planner een import uitvoert (cron of REST), stelt deze Importer::set_cron_image_queue( true ) in als as24ci_cron_image_queue op 1 staat (de standaardinstelling). Voor elk voertuig met meer dan één afbeelding doet de importer het volgende:

1. Downloadt alleen de eerste afbeelding onmiddellijk via het synchrone pad, zodat het voertuig een uitgelichte afbeelding heeft.
2. Controleert vooraf of elke resterende afbeelding al is gekoppeld (via de ontdubbelingsmap). Zo ja, dan wordt er geen wachtrij-item gemaakt en wordt de definitieve _as24ci_images_hash onmiddellijk weggeschreven.
3. Roept anders enqueue_remaining_images() aan om items in de vorm { post_id, listing_id, url, images_hash } toe te voegen aan de optie as24ci_image_queue. De _as24ci_images_hash van het voertuig wordt ingesteld op de sentinel 'pending_queue', zodat toekomstige imports blijven herwaarderen totdat de wachtrij is voltooid.

De wachtrij is hard begrensd op Scheduler::IMAGE_QUEUE_SIZE_LIMIT items. Nieuwe items worden genegeerd wanneer de limiet is bereikt en er wordt een logregel gegenereerd.

Wachtrij-worker

AS24CI\Scheduler::run_image_queue() is gekoppeld aan de cron-hook as24ci_image_queue_process en voert de daadwerkelijke uitgestelde downloads uit:

1. Roept set_time_limit(300) aan (onderhevig aan hostbeperkingen).
2. Verkrijgt de tijdelijke vergrendeling as24ci_image_queue_running (transient lock) met de TTL Scheduler::IMAGE_QUEUE_LOCK_TTL. Een verouderde vergrendeling (ouder dan de TTL) wordt automatisch gewist.
3. Laadt de wachtrij uit de optie as24ci_image_queue.
4. Verwerkt items in batches van Scheduler::IMAGE_QUEUE_BATCH_SIZE zolang de wachtrij niet leeg is en het tijdsbudget (IMAGE_QUEUE_LOCK_TTL − 60s) niet is uitgeput.
5. Roept voor elk item Image_Importer::import_images() aan voor de afzonderlijke URL. Fouten worden opgevangen en gelogd; het item wordt verwijderd om een oneindige foutlus (poison-pill loop) te voorkomen.
6. Slaat de resterende wachtrij op en schrijft statistieken per run naar as24ci_image_queue_last_run ({ processed, failed, remaining, timestamp }).
7. Bouwt voor elk bericht dat tijdens deze run volledig uit de wachtrij is verwerkt, _as24ci_image_ids gezaghebbend opnieuw op uit de werkelijke onderliggende bijlagen die zijn getagd met _as24ci_source_url en slaat de definitieve _as24ci_images_hash op. Dit garandeert dat de meta compleet en consistent is, zelfs als individuele wachtrij-items zijn mislukt.
8. Plant de volgende run via maybe_schedule_image_queue_worker() als er nog items over zijn.

De images_hash-waarde van de worker wordt vóór gebruik gevalideerd als een 32-tekens lange lowercase MD5-tekenreeks. Beschadigde items worden als afwezig behandeld, zodat de hash van het bericht niet wordt afgerond op basis van onjuiste gegevens.

Configuratiereferentie

De exacte waarden van IMAGE_QUEUE_LOCK_TTL, IMAGE_QUEUE_BATCH_SIZE en IMAGE_QUEUE_SIZE_LIMIT zijn gedefinieerd als constanten op AS24CI\Scheduler en kunnen tussen plugin-versies veranderen. Controleer ze in de huidige broncode als u een specifieke belasting wilt plannen.

Operationele opmerkingen

• WP-Cron is de standaard trigger. Overweeg op websites met weinig verkeer een server-side cron / systeem-cron die verwijst naar wp-cron.php (met DISABLE_WP_CRON ingesteld op true), zodat de wachtrij voorspelbaar leegloopt.
• Downloads van afbeeldingen worden uitgevoerd via download_url(), dat gebruikmaakt van de HTTP-API van WordPress. Hosts die uitgaand HTTP-verkeer blokkeren, moeten de AutoScout24-afbeeldingshosts op de whitelist zetten.
• Ontdubbeling van afbeeldingen is gebaseerd op de exacte bron-URL. URL's die alleen verschillen in de query-string of handtekeningparameters worden behandeld als afzonderlijke bronnen en apart gedownload.
• Handmatige galerijbijlagen die worden bijgehouden in _as24ci_manual_image_ids worden nooit overschreven of verwijderd door de importer of de wachtrij-worker.
• De wachtrij-worker bouwt _as24ci_image_ids aan het einde van elk volledig verwerkt bericht opnieuw op uit de werkelijke onderliggende bijlagen; als u de meta rechtstreeks tussen worker-runs manipuleert, kunnen uw wijzigingen ongedaan worden gemaakt.

Problemen oplossen

• Voertuigen verschijnen zonder afbeeldingen. Controleer of as24ci_import_images is ingeschakeld. Controleer of as24ci_max_images niet op nul staat waar dat de bedoeling is. In cron-modus wordt de primaire afbeelding synchroon geïmporteerd; als er helemaal geen afbeeldingen verschijnen, controleer dan het plugin-logboek op downloadfouten.
• Alleen de eerste afbeelding is aanwezig na een cron-import. Dit is verwacht tijdens imports in cron-modus totdat de as24ci_image_queue_process-worker klaar is. Controleer as24ci_image_queue_last_run voor de voortgang en de wachtrijgrootte.
• De wachtrij groeit maar loopt nooit leeg. Controleer of WP-Cron actief is (of dat een server-cron wp-cron.php triggert). Controleer op een vastgelopen as24ci_image_queue_running-transient die ouder is dan de TTL van de worker. De worker wist automatisch verouderde vergrendelingen bij de volgende run.
• WebP-conversie vindt niet plaats. Zorg ervoor dat as24ci_convert_to_webp op 1 staat en dat ofwel GD met WebP-ondersteuning (imagewebp) of Imagick is geïnstalleerd. De plugin logt de reden wanneer conversie wordt overgeslagen.
• Er verschijnen dubbel uitziende afbeeldingen in de galerij. De ontdubbelingssleutel is de exacte bron-URL. CDN's die unieke queryparameters per verzoek toevoegen, omzeilen de ontdubbeling. Controleer de URL's in de API-payload via gedetailleerde logboekregistratie (verbose logging).
• Afbeeldingen zijn verdwenen na het verwijderen van een voertuig. De Vehicle_Deleter verwijdert bijlagen die worden bijgehouden in _as24ci_image_ids. Handmatige galerijbijlagen (_as24ci_manual_image_ids) blijven behouden. Controleer in welke lijst de betreffende bijlage-ID stond.

Gerelateerde documenten

• Import Engine
• Cron Events And Scheduler
• Data Model
• Database Schema
• Overzicht