Bild-Importer und Warteschlange

Dieses Dokument beschreibt, wie das ADP Car Market Hub Plugin Fahrzeugbilder herunterlädt, dedupliziert und anhängt und wie die asynchrone Bildwarteschlange zeitaufwendige Bildarbeiten aus dem synchronen Importpfad auslagert.

Wann Sie dieses Dokument lesen sollten

Lesen Sie dieses Dokument, wenn Sie Folgendes tun müssen:

• Verstehen, welche Bilder in der WordPress Mediathek landen und welche wiederverwendet oder übersprungen werden.
• Fehlende, veraltete oder doppelte Fahrzeugbilder diagnostizieren.
• Die WebP-Konvertierung oder Speicherkapazität für einen großen Katalog planen.
• Die Bildverarbeitung im Cron-Modus für langsames oder eingeschränktes Hosting optimieren.

Für den übergeordneten Import-Ablauf siehe Import-Engine. Für die cron-seitige Planung siehe Cron-Events und Scheduler.

Übersicht

Zwei Klassen teilen sich die Verantwortung für die Bildverarbeitung:

• AS24CI\Image_Importer – lädt eine Liste von Bild-URLs herunter, konvertiert sie optional in WebP, hängt sie über media_handle_sideload() an einen Fahrzeug-Beitrag an und speichert die Quell-URL in den Attachment-Postmeta zur Deduplizierung.
• AS24CI\Scheduler – verwaltet die asynchrone Bildwarteschlange. Der Worker-Hook as24ci_image_queue_process verarbeitet ausstehende Elemente in Batches mit einer eigenen transienten Sperre und einem Zeitbudget.

Der Importer (Import-Engine) entscheidet basierend auf dem Cron-Modus des aktuellen Durchlaufs, ob Bilder synchron importiert oder die meisten davon in die Warteschlange verschoben werden.

Datenquelle (Source of Truth) für Bilder

Für jeden importierten Anhang ist die kanonische Markierung „Woher stammt das?“ das _as24ci_source_url Postmeta auf dem Anhang-Beitrag (Attachment). Das Plugin verwendet diese Markierung, um:

• Downloads zu deduplizieren – wenn bereits ein Anhang mit derselben Quell-URL existiert, verwendet das Plugin diesen wieder, anstatt ihn erneut herunterzuladen.
• Die _as24ci_image_ids-Liste des Fahrzeugs nach Abschluss des Queue-Workers autoritativ neu aufzubauen, indem untergeordnete Anhänge mit diesem Meta-Schlüssel abgefragt werden.

Zwei Postmeta-Schlüssel auf dem Fahrzeug-Beitrag verfolgen importierte Bilder:

• _as24ci_image_ids – Array von WordPress Anhang-IDs, die zur Galerie des Importers gehören.
• _as24ci_images_hash – MD5-Hash der Quellbildliste. Kann den Platzhalter 'pending_queue' enthalten, während sich Elemente noch in der Warteschlange befinden. Der nächste Import behandelt 'pending_queue' als Abweichung, sodass die Bildliste immer wieder neu bewertet wird, bis sie vollständig importiert ist.

Manuell hinzugefügte Galerie-Anhänge werden separat in _as24ci_manual_image_ids erfasst und vom Plugin niemals gelöscht.

Synchroner Bildimport

Image_Importer::import_images( int $post_id, array $images, string $listing_id ) führt die synchrone Arbeit aus:

1. Lädt bei Bedarf (lazy) die WordPress Medien-Admin-Dateien (wp-admin/includes/media.php, file.php, image.php).
2. Wendet defensiv die as24ci_max_images-Berechtigung erneut an.
3. Ruft die bekannten Quell-URLs des Beitrags einmalig über prefetch_known_urls_for_post() ab, um N Datenbankabfragen pro Bild zu vermeiden.
4. Für jedes Bild (String-URL oder Array mit den Schlüsseln url / src / href / original / imageUrl): - Verwendet einen vorhandenen Anhang wieder, wenn die Quell-URL bereits bekannt ist (zuerst In-Memory-Map, dann eine _as24ci_source_url-Postmeta-Abfrage). - Ruft andernfalls download_url( $url, 30 ) auf (30 Sekunden Timeout), konvertiert optional in WebP und ruft media_handle_sideload() auf, um den Anhang zu erstellen. - Schreibt _as24ci_source_url auf den neuen Anhang und fügt ihn der In-Memory-Deduplizierungs-Map hinzu. - Protokolliert Fehler (Download-Fehler, Sideload-Fehler) und fährt mit dem nächsten Bild fort.
5. Führt die neuen Anhang-IDs in _as24ci_image_ids zusammen (wobei zuvor importierte Elemente erhalten bleiben) und setzt das Beitragsbild (Post Thumbnail) auf den ersten Anhang, sofern der Beitrag noch keines hat.

Bestehende IDs werden zusammengeführt und nicht überschrieben, sodass Aufrufe des Queue-Workers Anhänge für denselben Beitrag über mehrere Durchläufe hinweg ansammeln.

WebP-Konvertierung

Wenn as24ci_convert_to_webp auf 1 steht, versucht der Importer, jedes heruntergeladene Bild vor dem Sideloading in WebP zu konvertieren:

• Die Qualität wird aus as24ci_webp_quality ausgelesen (Standardwert 80, falls nicht gesetzt) und auf den Bereich 1–100 begrenzt. Der Filter as24ci_webp_quality kann diesen Wert überschreiben.
• GDs imagewebp() wird zuerst versucht; Imagick wird als Fallback verwendet.
• Wenn keine der Erweiterungen verfügbar ist, wird die Konvertierung übersprungen, das Originalbild per Sideload geladen und ein Protokolleintrag erstellt.
• Wenn die Konvertierung eine leere Datei erzeugt oder fehlschlägt, wird die temporäre Datei bereinigt und das Originalbild verwendet.

Die konvertierte Datei übernimmt den ursprünglichen Dateinamen, wobei die Endung durch .webp ersetzt wird.

Import im Cron-Modus (Warteschlange)

Wenn der Scheduler einen Import ausführt (Cron oder REST), setzt er Importer::set_cron_image_queue( true ), wenn as24ci_cron_image_queue auf 1 steht (Standard). Für jedes Fahrzeug mit mehr als einem Bild führt der Importer Folgendes aus:

1. Lädt nur das erste Bild sofort über den synchronen Pfad herunter, damit das Fahrzeug ein Vorschaubild hat.
2. Prüft vorab, ob jedes verbleibende Bild bereits angehängt ist (über die Deduplizierungs-Map). Wenn ja, wird kein Warteschlangeneintrag erstellt und das finale _as24ci_images_hash sofort geschrieben.
3. Ruft andernfalls enqueue_remaining_images() auf, um Elemente im Format { post_id, listing_id, url, images_hash } an die Option as24ci_image_queue anzuhängen. Das _as24ci_images_hash des Fahrzeugs wird auf den Platzhalter 'pending_queue' gesetzt, sodass zukünftige Importe die Bewertung so lange wiederholen, bis die Warteschlange abgearbeitet ist.

Die Warteschlange ist hart auf Scheduler::IMAGE_QUEUE_SIZE_LIMIT Elemente begrenzt. Neue Einträge werden verworfen, wenn das Limit erreicht ist, und ein Protokolleintrag wird erstellt.

Queue-Worker

AS24CI\Scheduler::run_image_queue() ist an den Cron-Hook as24ci_image_queue_process gebunden und führt die eigentlichen verzögerten Downloads aus:

1. Ruft set_time_limit(300) auf (unter Berücksichtigung von Host-Einschränkungen).
2. Erwirbt die transiente Sperre as24ci_image_queue_running mit der TTL Scheduler::IMAGE_QUEUE_LOCK_TTL. Eine veraltete Sperre (älter als die TTL) wird automatisch gelöscht.
3. Lädt die Warteschlange aus der Option as24ci_image_queue.
4. Verarbeitet Elemente in Batches von Scheduler::IMAGE_QUEUE_BATCH_SIZE, solange die Warteschlange nicht leer ist und das Zeitbudget (IMAGE_QUEUE_LOCK_TTL − 60s) nicht erschöpft ist.
5. Ruft für jedes Element Image_Importer::import_images() für die einzelne URL auf. Fehler werden abgefangen und protokolliert; das Element wird verworfen, um eine Endlosschleife durch fehlerhafte Elemente (Poison Pills) zu vermeiden.
6. Speichert die verbleibende Warteschlange und schreibt Statistiken pro Durchlauf in as24ci_image_queue_last_run ({ processed, failed, remaining, timestamp }).
7. Baut für jeden Beitrag, der in diesem Durchlauf vollständig aus der Warteschlange abgearbeitet wurde, _as24ci_image_ids autoritativ aus den tatsächlichen untergeordneten Anhängen neu auf, die mit _as24ci_source_url markiert sind, und speichert das finale _as24ci_images_hash. Dies garantiert, dass die Metadaten vollständig und konsistent sind, selbst wenn einzelne Warteschlangenelemente fehlgeschlagen sind.
8. Plant den nächsten Durchlauf über maybe_schedule_image_queue_worker(), falls noch Elemente vorhanden sind.

Der images_hash-Wert des Workers wird vor der Verwendung als 32-stelliger, kleingeschriebener MD5-String validiert. Beschädigte Einträge werden als nicht vorhanden behandelt, damit der Beitrags-Hash nicht mit fehlerhaften Daten finalisiert wird.

Konfigurationsreferenz

Die genauen Werte von IMAGE_QUEUE_LOCK_TTL, IMAGE_QUEUE_BATCH_SIZE und IMAGE_QUEUE_SIZE_LIMIT sind als Konstanten in AS24CI\Scheduler definiert und können sich zwischen Plugin-Versionen ändern. Überprüfen Sie diese im aktuellen Quellcode, wenn Sie eine bestimmte Last planen müssen.

Betriebshinweise

• WP-Cron ist der Standard-Trigger. Bei Websites mit geringem Traffic sollten Sie einen serverseitigen Cron / System-Cron in Betracht ziehen, der auf wp-cron.php verweist (wobei DISABLE_WP_CRON auf true gesetzt ist), damit die Warteschlange zuverlässig abgearbeitet wird.
• Bild-Downloads werden über download_url() durchgeführt, was die HTTP-API von WordPress nutzt. Hosts, die ausgehenden HTTP-Verkehr blockieren, müssen die AutoScout24-Bild-Hosts auf die Whitelist setzen.
• Die Bild-Deduplizierung basiert auf der exakten Quell-URL. URLs, die sich nur im Query-String oder in Signatur-Parametern unterscheiden, werden als unterschiedliche Quellen behandelt und separat heruntergeladen.
• Manuelle Galerie-Anhänge, die in _as24ci_manual_image_ids erfasst sind, werden vom Importer oder dem Queue-Worker niemals überschrieben oder entfernt.
• Der Queue-Worker baut _as24ci_image_ids am Ende jedes vollständig abgearbeiteten Beitrags aus den tatsächlichen untergeordneten Anhängen neu auf; wenn Sie die Metadaten zwischen Worker-Durchläufen direkt manipulieren, werden Ihre Änderungen möglicherweise rückgängig gemacht.

Fehlerbehebung

• Fahrzeuge werden ohne Bilder angezeigt. Stellen Sie sicher, dass as24ci_import_images aktiviert ist. Überprüfen Sie, ob as24ci_max_images wie gewünscht ungleich Null ist. Im Cron-Modus wird das Hauptbild synchron importiert; wenn überhaupt keine Bilder angezeigt werden, suchen Sie im Plugin-Protokoll nach Download-Fehlern.
• Nach einem Cron-Import ist nur das erste Bild vorhanden. Dies ist während des Imports im Cron-Modus normal, bis der as24ci_image_queue_process-Worker fertig ist. Überprüfen Sie as24ci_image_queue_last_run auf den Fortschritt und die Warteschlangengröße.
• Die Warteschlange wächst, wird aber nie abgearbeitet. Stellen Sie sicher, dass WP-Cron läuft (oder dass ein Server-Cron wp-cron.php auslöst). Suchen Sie nach einer hängengebliebenen transienten Sperre as24ci_image_queue_running, die älter als die TTL des Workers ist. Der Worker löscht veraltete Sperren beim nächsten Durchlauf automatisch.
• Es findet keine WebP-Konvertierung statt. Stellen Sie sicher, dass as24ci_convert_to_webp auf 1 steht und dass entweder GD mit WebP-Unterstützung (imagewebp) oder Imagick installiert ist. Das Plugin protokolliert den Grund, wenn die Konvertierung übersprungen wird.
• Doppelt wirkende Bilder erscheinen in der Galerie. Der Deduplizierungsschlüssel ist die exakte Quell-URL. CDNs, die pro Anfrage eindeutige Query-Parameter anhängen, verhindern die Deduplizierung. Überprüfen Sie die URLs in den API-Daten über die detaillierte Protokollierung (Verbose Logging).
• Bilder sind nach dem Löschen eines Fahrzeugs verschwunden. Der Vehicle_Deleter entfernt Anhänge, die in _as24ci_image_ids erfasst sind. Manuelle Galerie-Anhänge (_as24ci_manual_image_ids) bleiben erhalten. Überprüfen Sie, in welcher Liste die betroffene Anhang-ID enthalten war.

Zugehörige Dokumente

• Import-Engine
• Cron-Events und Scheduler
• Datenmodell
• Datenbankschema
• Sektionsübersicht