Smart WebP Optimizer

A WordPress plugin that compresses and converts Media Library images to WebP, targeting a small file size without sacrificing quality or breaking your layout — then keeps your pages pointed at the optimized files and fills in missing alt text.

It does not just convert to WebP; it searches both quality and (optionally) dimensions to hit a real size budget, while keeping the high-resolution images your theme and page builder depend on.

How compression works

Each image (and each registered sub-size) is driven toward a two-tier size budget, highest visual quality first:

1. Lossless first (PNG graphics) — for PNG sources (screenshots, logos, line art), the plugin tries true lossless WebP. If the lossless file fits your budget it is used as-is, with zero quality loss. (Requires Imagick with WebP, or PHP 8.1+ GD.)
2. Target (default 75 KB) — otherwise the image is compressed with high-quality lossy WebP to land under this size while keeping quality at or above the floor.
3. Maximum (default 200 KB) — used only when the target can't be met without dropping below the minimum quality.
4. Best effort — when even the maximum can't be reached, the smallest valid WebP is kept (and clearly flagged in the results).

Already-used images are served as WebP automatically

Converting a Media Library image renames its file (image.jpg → image-swo.webp), so URLs hard-coded into existing pages, widgets, and page builders would otherwise keep loading the original. With Serve WebP on the front end (on by default), the plugin rewrites those image URLs to their WebP versions in the rendered page output — across the Block editor, Classic editor, and every page builder — so you never have to re-insert images page by page. It's applied at output only (the database isn't touched), so it's instant and fully reversible: a rollback stops serving WebP for that image. Optionally, Also rewrite image URLs permanently in content bakes the change into post/page content for the standard editors.

Your layout is safe by default

Resizing is off by default. The plugin changes format and quality, never your image dimensions, so featured images, hero/full-width sections, galleries, and page-builder layouts keep their full resolution. If you opt in to resizing (Settings → Allow resizing large images), it will never shrink an image below your configured minimum dimension — there is no destructive "collapse to a thumbnail" behaviour.

Originals are always preserved, so every change is reversible from the Rollback action.

Page builders & serialized content

The "Replace page and post image URLs" option rewrites image URLs in standard post content (Classic and Block editor). Because original files are always kept, builder-stored content (e.g. Elementor, Beaver Builder) keeps rendering its images normally. Posts that contain PHP-serialized data are intentionally skipped during URL replacement to avoid corrupting them — the optimizer logs when this happens.

Requirements & compatibility

• WordPress 6.0+, PHP 7.4+
• An image editor with WebP support (Imagick or GD). The admin screen warns you up front if WebP isn't available.
• All CSS, JS, options, meta keys, REST routes and hooks are namespaced (swo / SWO_) and admin assets load only on the optimizer screen, so the plugin stays out of the way of themes, builders, and other plugins.

Admin

Find it under Media → Image Optimizer:

• Dashboard — live stats, a one-click Scan → Optimize flow, a streaming results feed (original → new size, savings, outcome), pause/resume, and rollback.
• Settings — size budget, minimum quality, resizing limits, and automation (auto-optimize uploads, re-optimize from originals, alt text, URL replacement).
• Activity Log — a record of recent runs.

Updates (handled through GitHub)

This plugin updates itself from this repository's GitHub Releases — no wordpress.org listing required. Once installed, new versions appear under Plugins → Installed Plugins like any other update.

Shipping a new version

1. Bump the Version: header and the VERSION constant in smart-webp-optimizer.php (keep them in sync).
2. Commit and push to main.
3. Tag the release and push the tag:

   git tag v1.2.0
   git push origin v1.2.0

4. The included GitHub Action (.github/workflows/release.yml) builds a clean plugin zip (excluding .github/, dev files via .distignore) and attaches it to a new Release for that tag. The built-in updater prefers that asset, so production installs never receive CI/dev files. Within the update cache window (~6 hours, or immediately via Dashboard → Updates → Check again), connected sites are offered the update.

The version in the header and the release tag must match (a leading v is optional, e.g. v1.2.0 or 1.2.0).

Private repositories

If you make this repo private, define a token in wp-config.php so sites can authenticate to the API and download:

define( 'SWO_GITHUB_TOKEN', 'ghp_your_token_with_repo_scope' );

Private release assets are downloaded through the GitHub API asset endpoint with the token; the token is scoped to GitHub's API/codeload hosts only and is never sent to the storage redirect target.

Changelog

1.3.1

• Updater reliability: added a “Check for updates” link on the Plugins screen that clears the plugin's release cache and WordPress's update transient and forces an immediate re-check — so the Update button appears right away instead of waiting for the cache to expire (important on sites with wp-cron disabled).
• Added the WordPress 5.8+ update_plugins_github.com detection path alongside the existing transient injection, for maximum compatibility.
• A confirmation notice reports whether an update was found. No changes to image handling or site data.

1.3.0

• Serve WebP on the front end automatically. Image URLs already used in pages, widgets, and page builders (Elementor, Divi, Beaver, etc.) are rewritten to their WebP versions at output time — no need to re-insert images page by page. Works across all editors/builders because it operates on the rendered HTML, touches no database rows, and is reversible (rollback stops serving WebP). On/by default; an optional setting still rewrites the database permanently for the standard editors.
• A one-time migration builds the delivery map from images converted before this version, so existing conversions benefit immediately after updating.
• Scheme-aware matching (http/https) so SSL-migrated sites are covered. Map entries are removed on rollback and on attachment deletion.

1.2.0

• Fixed the layout breakage on live sites. Resizing is now off by default: the optimizer changes format/quality only and preserves your registered full/large image dimensions, so themes, page builders, and galleries keep their high-resolution images.
• Removed the destructive "shrink below the minimum dimension toward 200 px" fallback. When resizing is enabled, images are never reduced below your configured minimum dimension.
• Lossless WebP for PNG graphics when it fits the size budget (Imagick or PHP 8.1+ GD), with automatic high-quality lossy fallback.
• URL replacement now skips posts containing serialized data to prevent corruption, and logs when it does.
• Admin now warns up front when the server lacks WebP support, surfaces final dimensions / lossless state per image, and reports partial rollback failures.
• Updater: correct authenticated download path for private-repo release assets; release workflow ships a clean plugin zip via .distignore.
• Robustness: multisite-aware activation (and new-site seeding), uninstall.php cleanup, text-domain loading, single grouped status-count query, primed meta cache during scans, and a temp-dir writability fallback.

1.1.1

• Load the GitHub updater defensively so a missing file never blocks activation.

1.1.0

• Real two-tier compression, redesigned admin UI, and GitHub-based updates.

License

GPL-2.0-or-later.