Image Optimizate

Overview

Image Optimizate helps you optimize WordPress media images with:

• automatic optimization on upload
• single-image optimization from the Media Library and attachment screen
• queued bulk optimization for existing libraries
• restore support for backed-up originals
• logs and queue visibility in the WordPress admin

The plugin is managed from:

• Media > Image Optimizate

Requirements

• WordPress 6.4 or newer
• PHP 8.0 or newer

Depending on the engine you choose:

• Fallback: no extra runtime required beyond standard WordPress image editor support
• Browser Squoosh: no server-side Node.js required, but an authenticated admin browser tab must stay open while processing
• Server Squoosh: requires Node.js and the plugin’s Squoosh runtime dependencies

Admin Tabs

The plugin page has three tabs:

• Settings
• Bulk Optimize
• Logs

Settings

Optimize On Upload

When enabled, newly uploaded images are automatically optimized during upload processing.

Behavior:

• successful upload-time optimizations are logged
• skipped upload-time optimizations are logged
• failed upload-time attempts are queued for later retry

Processing Engine

You can choose one of three engines.

Fallback (GD/Imagick only)

Uses the WordPress image editor stack available on the host.

Best for:

• maximum compatibility
• hosting environments without Node.js
• simpler optimization workflows

Browser Squoosh (manual bulk run)

Uses local Squoosh codecs inside the admin browser.

Best for:

• hosts without Node.js
• users who still want Squoosh-based optimization

Important:

• queue preparation still happens in WordPress
• actual optimization only runs while an admin keeps the Bulk Optimize tab open
• closing or navigating away from that page stops processing

Server Squoosh (Node.js)

Uses the bundled Squoosh worker on the server.

Best for:

• environments where Node.js is available
• users who want server-side Squoosh processing without keeping a browser tab open

If the runtime is unavailable, the plugin shows a runtime warning and may switch to Browser Squoosh automatically.

Input Formats To Optimize

You can limit optimization to:

• JPEG
• PNG
• WebP
• AVIF

Only enabled input MIME types are queued and processed.

Output Mode

Two output modes are available.

Replace Original (in-place)

The optimized file replaces the currently attached file.

This is the default mode.

Create Additional Optimized File

Creates an additional optimized file instead of replacing the original attachment file.

Output Format

Available output formats:

• Same as source
• JPEG
• PNG
• WebP
• AVIF

Use Same as source if you want to preserve the original format.

Skip Small Images

When enabled, the plugin can skip images below configured thresholds:

• minimum file size in KB
• minimum width in pixels
• minimum height in pixels

Only Keep If Smaller

When enabled, optimized output is only kept if it is smaller than the original file.

Create Backups

When enabled, the plugin stores a backup before in-place replacement so the original can be restored later.

Queue Batch Size

Controls how many queued items are processed per queue run.

Current allowed range:

• minimum 1
• maximum 10

Per-Format Controls

The plugin includes format-specific controls for:

• JPEG quality
• JPEG progressive mode
• WebP quality
• WebP effort
• AVIF quality
• AVIF speed
• PNG level

Lower quality settings usually reduce file size more aggressively, but may also reduce visual quality.

Runtime Status

The Settings tab includes a Runtime Status card.

Use it to:

• confirm which engine is practical on the current host
• verify whether Server Squoosh is available
• re-check runtime support after environment changes

The Re-check runtime button refreshes the runtime detection from the server.

Bulk Optimize

The Bulk Optimize tab is used for queue-based processing.

Bulk Queue Controls

Available actions:

• Queue all eligible images
• Force requeue all images
• Process next batch now
• Retry failed
• Repair image references

Queue All Eligible Images

Adds all eligible image attachments to the optimization queue.

Force Requeue All Images

Requeues items even if they were previously optimized.

Process Next Batch Now

Runs the next queue batch immediately using the currently selected engine.

Retry Failed

Moves failed queue items back to pending so they can be processed again.

Repair Image References

Scans optimized attachments and repairs old image URL references in saved content where needed.

Note:

• block-based post content is intentionally protected from direct HTML rewriting to avoid invalidating Gutenberg blocks

Browser Squoosh Runner

This section appears when Browser Squoosh is selected.

Buttons:

• Start browser optimization
• Stop

How it works:

1. WordPress queue items are prepared on the server.
2. The browser claims the next pending job.
3. Squoosh codecs run in the browser.
4. The optimized result is sent back to WordPress.
5. The queue row, logs, and media state are updated.

Important:

• keep the page open while processing
• this runner is intended for environments where server-side Node.js is not available

Queue Status

The queue status section shows:

• pending items
• processing items
• completed items
• skipped items
• failed items
• total queue count

Recent Queue Rows

Shows recent queue activity, including:

• attachment ID
• source
• status
• attempts
• updated time
• last error

Logs

The Logs tab shows:

• total optimized image count
• total bytes saved
• recent log entries

Each log entry includes:

• time
• attachment
• status
• saved bytes
• message

The Clear logs and stats button removes stored log entries and optimization totals.

Media Library Features

The plugin adds several Media Library enhancements.

Single-Image Optimization

You can optimize an individual image from:

• Media Library row actions
• the attachment details modal
• the attachment edit screen

Restore Original

If backups are enabled and a backup exists, you can restore the original image from:

• Media Library row actions
• the attachment edit screen

Filetype Badge On Thumbnails

In grid view, media thumbnails show a badge in the lower-right corner with:

• file size
• current file type
• an image marker if the attachment has already been optimized

Examples:

• 45kb • WEBP
• 2.2mb • JPG
• 45kb • WEBP 🖼️

Automatic Page Refresh After Direct Runs

After direct single-image or bulk-select optimizations complete in the Media Library, the page reloads so updated file state, thumbnails, and metadata are reflected cleanly.

Upload Optimization

When Optimize on upload is enabled:

• new uploads are marked for optimization
• optimization runs during attachment metadata generation
• successful and skipped upload optimizations are written to the Logs tab
• failures are queued for later processing

Permissions

The plugin is restricted to users with appropriate WordPress capabilities.

In practice:

• plugin settings and bulk/admin tools require manage_options
• direct media actions require media permissions such as upload_files and attachment edit access

Compatibility Behavior

If the environment does not meet the plugin’s minimum WordPress or PHP requirements, the plugin deactivates and shows an admin notice.

If Server Squoosh is selected but unavailable:

• the plugin warns in the admin
• Browser Squoosh may be selected automatically to keep the plugin usable

Uninstall Behavior

On uninstall, the plugin removes:

• plugin settings
• queue table data
• log entries
• optimization totals
• plugin transients
• scheduled queue events
• plugin post meta
• stored backup files referenced by plugin backup metadata

Multisite uninstall cleanup is supported.

Troubleshooting

Server Squoosh Is Unavailable

Check the Runtime Status card.

Common reasons:

• Node.js is missing
• proc_open is disabled
• Squoosh runtime dependencies were not installed
• the worker script or runtime files are missing

Browser Queue Does Not Progress

Check that:

• Browser Squoosh is selected
• the Bulk Optimize tab remains open
• the logged-in admin session is still active

Images Are Skipped

Common causes:

• input format is disabled
• the file is below skip thresholds
• Only keep if smaller rejected the result
• the image was already optimized with the current profile

Logs Look Empty

Recent versions log:

• upload-time optimizations
• direct single-image optimizations
• direct bulk-select optimizations
• queue processing runs

Older optimization runs from before logging fixes were added will not be backfilled.

Developers

This plugin is primarily user-facing. Its current third-party extension surface is intentionally small.

Public Extension API

At the moment, the plugin does not provide a dedicated, documented set of custom:

• action hooks
• filter hooks
• template tags
• helper functions for third-party extensions

If a stable extension API is added in a future release, it should be documented here.

Current Integration Notes

The plugin does register a custom scheduled hook internally:

• mbio_process_queue

This is used by the plugin’s own queue processing system. It should be treated as an implementation detail rather than a stable public API.

The plugin also stores internal data in options, post meta, and a custom queue table. These storage details are part of the plugin’s internal implementation and should not be relied on as a stable extension contract.

Recommended Approach For Integrators

If you need to build around the plugin today, prefer:

• standard WordPress media workflows
• standard attachment and upload hooks provided by WordPress core
• observing final attachment state after optimization rather than calling plugin internals directly

Maintenance Note

This file should be updated whenever plugin behavior, settings, workflows, supported runtimes, or developer extension points change.