Image Importer und Warteschlange

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

Wann Sie dieses Dokument verwenden 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 grossen 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 And 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-Post an und speichert die Quell-URL in den Attachment-Postmeta zur Deduplizierung.
• AS24CI\Scheduler — besitzt die asynchrone Bild-Warteschlange. Der Worker-Hook as24ci_image_queue_process verarbeitet ausstehende Elemente in Batches mit einer eigenen transienten Sperre und einem eigenen 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.

Source of Truth für Bilder

Für jedes importierte Attachment ist der kanonische Marker für „Woher stammt das?“ das _as24ci_source_url-Postmeta auf dem Attachment-Post. Das Plugin verwendet diesen Marker für Folgendes:

• Downloads deduplizieren — wenn bereits ein Attachment mit derselben Quell-URL existiert, verwendet das Plugin dieses wieder, anstatt es erneut herunterzuladen.
• Die _as24ci_image_ids-Liste des Fahrzeugs nach Abschluss des Queue-Workers autoritativ neu aufbauen, indem Child-Attachments mit diesem Meta-Key abgefragt werden.

Zwei Postmeta-Keys auf dem Fahrzeug-Post verfolgen importierte Bilder:

• _as24ci_image_ids — Array von WordPress-Attachment-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 neu bewertet wird, bis sie vollständig importiert ist.

Manuell hinzugefügte Galerie-Attachments werden separat in _as24ci_manual_image_ids verfolgt 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. Bindet die WordPress-Medien-Admin-Dateien (wp-admin/includes/media.php, file.php, image.php) verzögert (lazy) ein.
2. Wendet die as24ci_max_images-Berechtigung defensiv erneut an.
3. Ruft die bekannten Quell-URLs des Posts 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 Keys url / src / href / original / imageUrl): - Verwendet ein vorhandenes Attachment wieder, wenn die Quell-URL bereits bekannt ist (zuerst In-Memory-Map, dann ein _as24ci_source_url-Postmeta-Lookup). - Ruft andernfalls download_url( $url, 30 ) auf (30 Sekunden Timeout), konvertiert optional in WebP und ruft media_handle_sideload() auf, um das Attachment zu erstellen. - Schreibt _as24ci_source_url auf das neue Attachment und fügt es 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 Attachment-IDs in _as24ci_image_ids zusammen (wobei zuvor importierte Elemente beibehalten werden) und setzt das Beitragsbild (Post Thumbnail) auf das erste Attachment, falls der Post noch keines hat.

Bestehende IDs werden zusammengeführt und nicht überschrieben, damit Aufrufe des Queue-Workers Attachments für denselben Post ü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 gelesen (Standardwert 80, falls nicht gesetzt) und auf den Bereich 1–100 begrenzt. Der Filter as24ci_webp_quality kann den 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 Log-Eintrag erstellt.
• Wenn die Konvertierung eine leere Datei erzeugt oder fehlschlägt, wird die temporäre Datei bereinigt und das Originalbild verwendet.

Die konvertierte Datei erbt 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 ), falls 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 Beitragsbild 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, damit 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 Log-Eintrag 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 aufgehoben.
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 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 Post, der in diesem Durchlauf vollständig aus der Warteschlange abgearbeitet wurde, _as24ci_image_ids autoritativ aus den tatsächlichen Child-Attachments 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 MD5-String in Kleinbuchstaben validiert. Beschädigte Einträge werden als fehlend behandelt, damit der Post-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 wenig Traffic sollten Sie einen serverseitigen Cron / System-Cron in Betracht ziehen, der auf wp-cron.php zeigt (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-Attachments, die in _as24ci_manual_image_ids verfolgt werden, werden vom Importer oder dem Queue-Worker niemals überschrieben oder entfernt.
• Der Queue-Worker baut _as24ci_image_ids am Ende jedes vollständig abgearbeiteten Posts aus den tatsächlichen Child-Attachments neu auf. Wenn Sie die Metadaten zwischen Worker-Durchläufen direkt manipulieren, werden Ihre Änderungen möglicherweise rückgängig gemacht.

Fehlerbehebung

• Fahrzeuge erscheinen ohne Bilder. Vergewissern Sie sich, dass as24ci_import_images aktiviert ist. Stellen Sie sicher, dass as24ci_max_images an den gewünschten Stellen ungleich Null ist. Im Cron-Modus wird das Hauptbild synchron importiert. Wenn überhaupt keine Bilder erscheinen, suchen Sie im Plugin-Log nach Download-Fehlern.
• Nach einem Cron-Import ist nur das erste Bild vorhanden. Dies ist bei Importen im Cron-Modus normal, bis der as24ci_image_queue_process-Worker fertig ist. Überprüfen Sie as24ci_image_queue_last_run für den Fortschritt und die Warteschlangengrösse.
• 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 einem blockierten as24ci_image_queue_running-Transient, der älter als die TTL des Workers ist. Der Worker hebt veraltete Sperren beim nächsten Durchlauf automatisch auf.
• 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 Deduplizierungs-Key ist die exakte Quell-URL. CDNs, die bei jeder Anfrage eindeutige Query-Parameter anhängen, umgehen die Deduplizierung. Überprüfen Sie die URLs im API-Payload über das detaillierte Logging (Verbose Logging).
• Bilder sind nach dem Löschen eines Fahrzeugs verschunden. Der Vehicle_Deleter entfernt Attachments, die in _as24ci_image_ids verfolgt werden. Manuelle Galerie-Attachments (_as24ci_manual_image_ids) bleiben erhalten. Überprüfen Sie, in welcher Liste die betroffene Attachment-ID enthalten war.

Verwandte Dokumente

• Import Engine
• Cron Events And Scheduler
• Data Model
• Database Schema
• Übersicht