SEV WebP Migrator for W3TC

SEV WebP Migrator for W3TC is a companion plugin for W3 Total Cache that finishes the job once W3TC ImageService has converted an image to WebP.

No changes to .htaccess, mod_rewrite, or web server configuration are required. Instead, it writes the replacement back into the database once, unlike a runtime content filter that swaps URLs on every request: as soon as W3TC marks an attachment as converted, every occurrence of that image’s URL — in post_content, widget instances, and theme mod settings (e.g. a Customizer background image) — is permanently replaced, from its original extension (jpg/jpeg/png/gif) to .webp. This covers absolute, root-relative, and protocol-relative URL forms, since hand-authored content (most commonly the Customizer’s “Additional CSS” field) frequently omits the scheme and/or host. The attachment’s own record (attached file, metadata, mime type) is updated to match, so the Media Library and REST API stay consistent too.

Optionally, once an image has been fully replaced, the plugin can delete the now-unused original source files from disk to reclaim storage space.

This is an independent, unofficial add-on and is not affiliated with, endorsed by, or sponsored by BoldGrid / W3 EDGE, the makers of W3 Total Cache. “W3 Total Cache” is a trademark of its respective owner and is used here only to describe compatibility.

Features

• Listens for W3TC ImageService conversions and reacts automatically.
• Regenerates any intermediate size W3TC itself failed to convert (this can happen silently, e.g. for Site Icon sizes that are only registered in certain admin contexts) directly from the already-converted full-size WebP, instead of waiting indefinitely for an event that never comes.
• Replaces every reference to the converted image (full size and all intermediate sizes) — in post_content across all posts, widget instances, and theme mod settings — as absolute, root-relative, or protocol-relative URLs.
• Updates the attachment’s own file reference, metadata, and mime type to match.
• Optional: deletes the original source files after a successful replacement.
• A source file is only ever deleted once its .webp counterpart has been confirmed to exist on disk.
• Manual “process now” tool in Settings → WebP Migrator for W3TC for images that were converted before this plugin was active.
• Diagnostic logging (behind WP_DEBUG_LOG) explains exactly why an image was skipped, to help troubleshoot a batch that makes no progress.
• Also corrects an image reference at the moment a post is saved, for the rare case where the image was inserted while still being converted in the background.
• Deletion of a freshly-uploaded image’s original files is deferred for a short grace period after upload, so it isn’t pulled out from under an editor session that might still be rendering it from the original URL.

How it works

1. W3 Total Cache ImageService converts an image and marks the attachment’s w3tc_imageservice post meta as converted.
2. This plugin detects that meta change and looks up every file W3TC generated for the attachment (full size and each registered thumbnail size).
3. If W3TC didn’t generate one of the intermediate sizes, the plugin regenerates it itself from the already-converted full-size WebP, so a single silently-skipped size doesn’t block the whole attachment forever.
4. It scans post_content across all posts, as well as widget instances and theme mod settings, for the old URLs — in absolute, root-relative, and protocol-relative form — and replaces them with the .webp versions directly in the database.
5. The attachment’s own _wp_attached_file, _wp_attachment_metadata, and post_mime_type are updated to point at the .webp files.
6. If enabled in the settings, the original files (jpg/jpeg/png/gif) are deleted from disk.

Requirements

• W3 Total Cache must be installed and active.
• Images must be converted using Media → W3TC Image Service; this plugin does not perform any conversion itself.

Limitations

This plugin does not convert images to WebP — conversion is handled entirely by W3 Total Cache ImageService. It only reacts once W3TC reports an image as converted.

This plugin only handles WebP. AVIF is not supported: W3 Total Cache only offers AVIF conversion in its paid Pro version, and this plugin’s free-tier ImageService integration only ever sees WebP conversions.

Content stored outside post_content, widget instances, and theme mods is not scanned — for example a page builder’s own design data stored in post meta (such as Elementor). If an image is referenced only from such a source, its URL there will not be updated.

Deleting source images is permanent and cannot be undone by this plugin. Keep backups before enabling automatic deletion.