Image Queue Maintenance

This document explains how the plugin's asynchronous image queue works, how to monitor its progress, and how to maintain, manually process, or clear the queue in production.

When to use this document

Read this document if you are a site administrator and you need to understand why vehicle images are not yet appearing after an import, why the image queue is growing, or how to manage image downloads on sites with large catalogues or constrained server resources.

Overview

When the Image queue mode is enabled (the default for scheduled and REST-triggered imports), the plugin does not download all vehicle images during the main import run. Instead:

1. Only the first image of each vehicle is downloaded immediately during the import.
2. The remaining image URLs are stored in a persistent queue in the WordPress options table (as24ci_image_queue).
3. After each import run, a separate image queue worker is scheduled as a WP-Cron single event to process the queued images in batches.
4. The worker runs repeatedly, processing 30 images per batch, until the queue is empty or the time budget is exhausted.

This approach keeps each import run short and predictable, even for catalogues with many images per vehicle.

For manual imports triggered from the Importer tab (not through cron or REST), queue mode is disabled by default and all images are downloaded immediately during the import.

How the image queue worker operates

The image queue worker:

1. Acquires its own transient lock (as24ci_image_queue_running, TTL 10 minutes) to prevent overlapping workers.
2. Reads the current queue from the as24ci_image_queue option.
3. Processes items in batches of 30 images, checking after each batch whether the time budget (the lock TTL minus 60 seconds, approximately 540 seconds) has been reached.
4. Writes the remaining queue back to the database after each batch.
5. Records run statistics (processed, failed, remaining, timestamp) in the as24ci_image_queue_last_run option.
6. If items remain after the time budget is exhausted, schedules another single WP-Cron event immediately so processing continues in the next available request.
7. Releases the lock when done.

After all queued items for a vehicle post have been processed, the worker rebuilds the _as24ci_image_ids post meta from the actual attachment IDs in the database and finalises the image hash, so the next import run can correctly detect future changes.

Image deduplication

The image importer deduplicates images by source URL. Before downloading an image, it checks whether an attachment with the same _as24ci_source_url post meta already exists. If a match is found, the existing attachment is reused rather than downloaded again. This applies to both immediate and queue-mode imports.

This means re-running an import or re-processing the queue will not create duplicate attachments for images that were already successfully imported.

WebP conversion

If the Convert to WebP option is enabled, each downloaded image is converted to WebP format before being added to the media library. The plugin tries GD first, then Imagick as a fallback. If neither is available or conversion fails, the original image format is used. Conversion results are logged at warning level when they fail.

WebP quality is configurable (1–100, default 80). The quality value can also be overridden at the code level via the as24ci_webp_quality filter.

Monitoring the image queue

System & Help tab

1. Open ADP Car Market Hub → System & Help.
2. In the Background Tasks table, find the Image Processor row (hook: as24ci_image_queue_process).
3. The Next Run column shows when the next worker invocation is scheduled.
4. The Status column shows: - Scheduled (green) — a worker event is queued - Running (amber) — the worker is currently active - Lock stuck (red) — a stale lock was detected; it will be auto-cleared on the next run attempt - Not scheduled (amber) — no worker is currently queued (expected when the queue is empty)
5. The System & Help tab shows a warning badge when the queue size exceeds 1,000 items, indicating that image processing is falling behind.

Image queue last-run stats

The plugin stores the results of the most recent worker run in the as24ci_image_queue_last_run option. These stats include:

• processed — images successfully downloaded in the last run
• failed — images that could not be downloaded
• remaining — items still waiting in the queue
• timestamp — Unix timestamp of the last run

These values are displayed in the System & Help tab and can be used to assess queue throughput.

Import & Limits tab

The Automation tab provides manual control actions for the image queue:

• Run image queue now — triggers the worker immediately via an AJAX request. Useful when you want to force image processing without waiting for the next scheduled event.
• Clear image queue — discards all pending items in the queue. Use this when you want to stop image processing, for example if a large batch of incorrect images was queued. This does not delete images that have already been downloaded.

Step-by-step: processing a stuck image queue

1. Open ADP Car Market Hub → System & Help.
2. Check the Background Tasks table for the Image Processor row. If the status is Not scheduled but the queue is not empty (the warning badge is visible or the last-run stats show a non-zero remaining count), the worker cron event was not re-scheduled.
3. Click Run Image Queue Now in the System & Help tab action bar to start a worker immediately.
4. Wait for the run to complete (typically a few seconds to a few minutes depending on queue size).
5. Refresh the System & Help tab to verify that the queue is decreasing.
6. If the worker runs but the queue is not decreasing (for example, if all images are failing), check the log for [ERROR] and [WARNING] entries related to Image queue worker or Image download failed.

Step-by-step: clearing the image queue

Use this procedure when you want to abandon all pending image downloads (for example, after removing a seller ID or after a bulk delete of vehicles).

1. Open ADP Car Market Hub → System & Help or Import & Limits.
2. Click Clear Image Queue.
3. Confirm the action when prompted.
4. The queue option is cleared and no further background image downloads will occur for the discarded items.
5. Vehicles that had their remaining images cleared will only have the first image (downloaded during the import run) until the next full import.

Queue size limits

The plugin imposes a hard limit of 20,000 items in the image queue. If the queue grows beyond this limit, a warning is logged and a deduplication pass is run to collapse duplicate entries. Verify this behavior in the current plugin version before publishing.

Configuration reference

Operational notes

• Image queue mode is only applied during imports triggered by WP-Cron or the REST cron endpoint. Manual imports from the Importer tab always download all images immediately (unless the max images limit applies).
• The image queue persists across import runs. If the worker has not finished processing a previous batch when a new import runs, the new image URLs are appended to the existing queue.
• If a vehicle post is deleted after its image URLs were queued but before the worker processes them, the worker silently skips items whose post no longer exists.
• The image queue stores per-item metadata including the vehicle post ID, the listing ID, the image URL, and an image hash. This allows the worker to finalize image hashes correctly after all images for a vehicle have been processed.
• On sites with large catalogues (hundreds of vehicles with many images each), the image queue may grow to several thousand items after the first import. This is expected behavior. The queue will decrease steadily over subsequent worker runs as long as WP-Cron (or the image-queue worker cron hook) is running.
• If disk space in the uploads directory is low, image downloads will fail. The System & Help tab shows disk space availability. Free space before running a large image import.

Troubleshooting

Related documents

• Import Monitoring
• Logging and Monitoring
• Daily Operation
• Weekly Maintenance