Compatibility & preflight

Open Media → Image Optimizer → Preflight before production bulk work. The report runs entirely on the WordPress server and does not send environment or image data to Amazing WP Plugins or an optimization service.

Backup-plugin integration

A backup plugin can satisfy the safety gate after it has verified a current, restorable database and uploads backup:

add_filter( 'aiofw_backup_status', function ( $status, $context ) {
    if ( my_backup_plugin_has_verified_current_backup() ) {
        $status['confirmed'] = true;
        $status['label'] = 'Verified backup available';
        $status['message'] = 'Database and uploads backup verified by My Backup Plugin.';
    }
    return $status;
}, 10, 2 );

The aiofw_backup_requirement_satisfied action runs after manual acknowledgement or an integration satisfies the gate. The plugin intentionally includes no offload, cloud optimization, telemetry, or remote image-processing feature.

Installation and quick start

1. Upload the plugin folder to wp-content/plugins/, or install its ZIP through Plugins → Add New → Upload Plugin.
2. Activate Amazing Image Optimizer for WordPress.
3. Open Media → Image Optimizer → License and activate the license key from your purchase.
4. Choose an image editor, processing mode, compression level, dimensions, and optional WebP/AVIF replacement.
5. Save settings and run Image Editor Test Drive before enabling a large conversion job.

License activation and updates

The License tab is the final tab under Media → Image Optimizer. Enter the license key from the purchase receipt or your amazingwpplugins.com account, then select Activate License.

• A valid license unlocks every plugin settings, reporting, and maintenance tab and enables licensed plugin updates.
• Without a valid license, those tab contents are replaced by an activation prompt. Media Library Optimize, Re-optimize, Convert, Repair references, and selected-image controls remain available.
• The active key is masked in wp-admin. The License tab shows its renewal date or Lifetime status and provides deactivation with local key removal.
• WordPress revalidates the key daily through native WP-Cron.

Settings reference

Export and import

The Export / import settings panel downloads or restores configuration as JSON. Queue records, statistics, conversion results, and debug events are not included. Importing replaces the current optimizer settings but does not alter images.

New upload workflow

Media Library, Gutenberg drag-and-drop, and other uploads that use WordPress’s standard attachment workflow receive the same processing.

• The dimension check happens before WordPress generates thumbnails.
• If the image is already within both limits, it is not resized.
• Because the plugin caps dimensions at 2560px, it normally prevents WordPress from needing a second -scaled copy.
• If WordPress still creates -scaled as a fallback, that active file is respected and heavy conversion is deferred to keep the upload response reliable.
• The Media Library displays a live activity panel for upload, resize checks, conversion, image-size generation, optimization, or queueing.

Media Library tools

List view

• Image optimization shows combined current size. Select the + control to reveal main-image and variant sizes.
• Optimize now runs through AJAX; after completion it becomes Re-optimize.
• Queue conversion to WebP/AVIF adds an existing JPEG/PNG to the persistent native WP-Cron worker. In the background it converts the attachment, regenerates sizes, and migrates stored database references. Converted WebP/AVIF attachments also provide Repair references for any remaining JPEG/PNG URLs.
• While conversion is queued or running, the conversion control and its conflicting Optimize/Re-optimize action remain disabled. The Media Library checks progress every five seconds and updates the row automatically when processing finishes—no page refresh is required.
• If neither WebP nor AVIF produces a smaller complete image set, the plugin keeps the original attachment. The row returns to its normal ready state and displays the recorded reason instead of remaining incorrectly marked as queued.
• Use filters for optimized, unoptimized, or failed images and sort by total image size.
• Use Optimize selected or Queue selected for WebP/AVIF for checked images. Selected conversions continue after the browser closes.
• The Uploaded to column includes the parent, a View/Preview link, and the post type.

Grid view and attachment popup

The grid toolbar includes optimization filters, size ordering, and selected-image actions. Opening an image’s attachment details displays its status and per-image Optimize/Convert controls.

Resize existing images

The dedicated Resize Images tab processes existing JPEG, PNG, WebP, and AVIF attachments whose active full-size file exceeds the maximum width or height saved under Settings.

• Only the active full-size image is resized; optimization and WebP/AVIF conversion do not run.
• The attachment ID, filename, URL, MIME type, and existing generated variants remain unchanged.
• The main width, height, filesize, current total size, and resize savings are updated.
• When Keep original is enabled, the first available plugin backup is retained. Otherwise, the temporary rollback copy is deleted only after metadata is safely saved.
• The resumable AJAX batch inspects the library in small chunks, resizes at most one oversized image per cycle, and supports pause, resume, and clear.

Convert existing images

The overview uses a WordPress-style metric-card and segmented-health layout. Before scanning it summarizes all supported Media Library images; after scanning it follows the current inventory. Optimization status updates after every processed image, while heavier storage aggregates refresh periodically and once more at completion. Older untouched images may not have byte tracking yet, so unavailable savings show as untracked rather than a misleading 0%.

Recommended workflow

1. Choose JPEG, PNG, or both as the source filter.
2. Choose Optimize only to retain the current format and URLs, or choose WebP, AVIF, or the smaller of both conversion outputs.
3. Optionally include only images with an Uploaded to parent.
4. Enable custom-table scanning only if required; it is broader and slower.
5. Choose whether successfully replaced JPEG/PNG files should be deleted.
6. Confirm the backup and click Scan existing images.
7. Review the paginated inventory. Images are selected by default; uncheck exclusions. Selections persist across pages.
8. Convert individual rows or start the resumable batch. The batch displays a live ETA after its first timed image; pause, resume, or retry failures when needed.

The scan first builds the filtered attachment inventory, then the Background Job Center catalogs database rows containing JPEG/PNG references one configured column at a time. This catalog continues building after the tab closes and is reused by every conversion in that inventory.

What is migrated?

The converter preserves attachment IDs and updates plain, URL-encoded, JSON-escaped, and serialized URL/path references in posts, post metadata, options, and supported database locations. The attachment parent is handled explicitly, including linked-image href, img src, and srcset references. It regenerates current registered sizes and converts legacy WIDTHxHEIGHT variants it discovers.

Each conversion is verified. On failure, the image is marked failed and the conversion attempts to roll back its files and data changes.

Originals & recovery

The Originals & Recovery tab inventories every original retained by the plugin. It reports backup count, disk usage, missing files, and provides paginated per-image and bulk actions.

• Restore puts the retained full-size image back and regenerates WordPress image sizes.
• If conversion changed the extension, the restore migrates stored paths and URLs back to the original format, then verifies that old converted references are gone.
• The current image set, attachment data, metadata, and reference rows are snapshotted first. A failed verification restores that snapshot.
• Delete backup reclaims backup storage without changing the active attachment. This cannot be undone by the plugin.

Delete unused replaced originals

Existing-image conversions that retain their replaced JPEG/PNG files track the complete source set. Use Validate current set to audit the active main image and every registered variant without deleting anything. After reviewing healthy WebP/AVIF results, use Validate and delete if unused individually or in bulk. Before deletion, the plugin repeats the full decode and performs a fresh reference check. It refuses deletion when the replacement is unhealthy or when an original is active, outside uploads, registered to another attachment, or still referenced.

Find retained originals discovers exact JPEG/PNG counterparts of WebP/AVIF attachments converted by earlier releases, including WordPress-style WIDTHxHEIGHT variants. Discovery only builds the inventory; it never deletes files.

Image Integrity & Repair

The Integrity & Repair tab performs a persistent, read-only audit of active Media Library images. It continues through the Background Job Center after the browser closes and restores live progress, completion percentage, and an ETA based only on active worker time when the tab is revisited. The Images per batch control has no upper cap and defaults to the suggested value of 20. Each audit reads both database metadata and files from disk, so increase it carefully to avoid I/O spikes and PHP timeouts. Use Save batch size at any time; a running or paused scan adopts the saved value on its next worker batch. The status reports the last individual worker-batch size. Because the browser refreshes progress every five seconds, the visible total can jump by two or more completed batches. Individual and bulk repairs display immediate spinner feedback; bulk work also reports handled/total counts, percentage, and a live progress bar, followed by a completed or error state.

• Detects missing or unreadable active files, files outside uploads, MIME mismatches, incomplete conversion markers, missing or incorrect metadata, missing registered image sizes, missing generated files, orphan dimension variants, and GUID filename differences.
• Repair is offered only when WordPress can deterministically rebuild the result from an existing, decodable main file.
• Repair all safe findings processes repairs in bounded AJAX groups to reduce timeout risk.
• Missing source files and ambiguous/orphaned files are report-only; the plugin does not guess or delete them.
• Export CSV report downloads the latest full findings list.

Unified Background Job Center

The Job Center provides one live dashboard for image optimization, existing-image conversion, resize-only batches, integrity audits, retained-original discovery, restoration, and verified cleanup. Persistent jobs continue through native WP-Cron after the browser closes.

WP-Cron and background processing

The plugin schedules a native WordPress event every minute. WP-Cron is traffic-driven, so the scheduled time is not a guarantee on low-traffic sites.

Reliable server cron

For predictable processing, invoke WordPress from the server’s cron scheduler. One common WP-CLI pattern is:

*/5 * * * * cd /path/to/wordpress && wp amazing-image run --batch=20 --quiet

Adjust the path, PHP/WP-CLI command, interval, and batch size for the hosting environment. If DISABLE_WP_CRON is enabled, ensure the server invokes either wp-cron.php or WP-CLI. While a worker is active, plugin and Media Library screens display a live progress bar with its source, current image, and handled count.

WP-CLI reference

convert-existing requires --yes to confirm a current database/uploads backup, unless a trusted backup-plugin integration confirms one through aiofw_backup_status. It shows progress and an ETA. Omit --attached-only to process unattached images too; omit --delete-old to retain replaced source files. Output may be webp, avif, or smallest. Add --custom-tables only when broader plugin/custom-table scanning is needed.

Builders, ACF, and WooCommerce

Conversions keep the same attachment ID. This is the safest path for WordPress features and plugins that store an image ID rather than a literal URL.

• Gutenberg: attachment IDs remain intact; URL references in block markup are migrated.
• Elementor and builders: URL references in JSON/serialized settings are migrated. Detected Elementor, Beaver Builder, and Divi generated caches are invalidated through their available APIs.
• ACF: image and gallery fields storing IDs continue to work; URL/array storage is included in recursive reference replacement.
• WooCommerce: featured and gallery image attachment IDs continue to resolve to the converted attachment and regenerated sizes.

Image Editor Test Drive

The Test Drive compares Imagick and GD with the saved settings, generating separate JPEG, WebP, and AVIF results where supported. It uses a readable Media Library image, prefers one over 1MB, and includes a retained full-resolution original when available. A generated demo is used only when no suitable site image exists.

• When Perceptual Auto-Quality is enabled, each card reports the lowest tested encoder quality that met the saved similarity target.
• Click any source or result image to inspect it at full size in a new tab.
• Use Try another image to exclude the displayed attachment and rerun the comparison with another readable Media Library image.
• Active editor identifies WordPress’s current first-choice editor.
• Would keep appears only on the smallest successful result.
• Each result shows its format-specific encoder quality and a local 64×64 luminance SSIM approximation. Treat it as a consistent comparison aid, not a laboratory perceptual metric.
• An unsupported result includes the editor’s error instead of presenting it as a valid option.

Developer hooks

Amazing Image Optimizer uses standard WordPress filters and actions so site-specific integrations can adjust local policy and observe operations without editing plugin files. Hooks run synchronously inside the request or background worker; callbacks should be fast, return the documented type, and must not throw exceptions.

Lifecycle actions

Queueing: aiofw_attachment_queued and aiofw_attachments_queued. Optimization: aiofw_before_attachment_optimization, aiofw_attachment_optimization_skipped, aiofw_attachment_optimization_failed, and aiofw_after_attachment_optimization. Conversion: aiofw_before_existing_attachment_conversion, aiofw_existing_attachment_conversion_skipped, aiofw_existing_attachment_conversion_failed, aiofw_after_existing_attachment_conversion, aiofw_attachment_converted, and aiofw_attachment_conversion_rolled_back. Resizing and integrity: aiofw_before_attachment_resize, aiofw_after_attachment_resize, and aiofw_attachment_integrity_inspected. Background work: aiofw_background_job_enqueued, aiofw_before_background_worker, aiofw_after_background_worker, aiofw_background_job_item_processed, and aiofw_background_job_completed.

Examples

// Exclude protected media from queueing.
add_filter( 'aiofw_should_queue_attachment', function ( $allowed, $attachment_id ) {
    return has_term( 'do-not-optimize', 'media_category', $attachment_id ) ? false : $allowed;
}, 10, 2 );

// Use a lower AVIF quality for a particular attachment.
add_filter( 'aiofw_attachment_settings', function ( $settings, $attachment_id ) {
    if ( 123 === $attachment_id ) {
        $settings['avif_quality'] = 45;
    }
    return $settings;
}, 10, 2 );

// Notify a local monitoring integration after a job completes.
add_action( 'aiofw_background_job_completed', function ( $job ) {
    error_log( sprintf( 'AIOFW job %s completed.', $job['id'] ) );
} );

Debugging

Debug logging is off by default. Enable it temporarily under Media → Image Optimizer → Debug, reproduce the problem once, then review the newest events.

• The log retains only the newest 250 events.
• Events cover resize decisions, active files, editor failures, conversion candidates, queue activity, and rollback outcomes.
• Use Clear debug log after troubleshooting and disable logging when finished.

Troubleshooting

Large upload finishes on disk but Media Library reports an error

Version 1.11.4 and newer avoid duplicate attachment-size generation by converting before attachment creation. Version 1.12.2 also polls conversion status when a proxy times out, so a conversion that continues successfully is recognized instead of shown as a false failure. Confirm the current plugin version, clear opcode/page caches, retry with Debug enabled, and inspect PHP memory/execution limits if the server still cannot decode the source.

AVIF reports “no encode delegate”

This is an image-library/server capability issue. The selected Imagick installation was built without a working AVIF/HEIF encoder. Ask the server administrator to enable AVIF support, or select GD/WebP when supported.

The converted image exists but an old URL remains

Clear WordPress, builder, object, reverse-proxy, and CDN caches. If the URL is stored in a proprietary table, restore from backup, enable advanced custom-table migration, and test again on staging.

WP-Cron is scheduled but nothing runs

Confirm images are actually queued. WP-Cron needs site traffic unless the server invokes it. Check Cron Status for disabled cron, stale work, the next run, and the latest outcome.

A failed image needs attention

Use the failed-image filter in list or grid Media Library view. The status displays the stored error. Enable Debug, reproduce with the per-image action, and review editor/memory/file-permission events.