Generate and serve WebP companions

For supported non-GIF images that are not already WebP, Image Optimizer creates a WebP file beside the source and beside each generated size.

The companion keeps the complete original filename and adds .webp:

photo.jpg
photo.jpg.webp

photo-300x200.jpg
photo-300x200.jpg.webp

Format rules

• JPEG, PNG, and AVIF attachments can receive WebP companions.
• A WebP upload is optimized as WebP and does not receive .webp.webp.
• GIF attachments do not receive WebP companions. Any matching companions are removed so an animated GIF is not replaced by a flattened conversion.
• A generated WebP must be non-empty and fully decodable before it replaces the previous companion. Failed conversions leave any existing companion unchanged.

Deleting an attachment removes the companions recorded for its main file and generated sizes.

Generation is not delivery

This module creates the files; it does not rewrite image URLs in page HTML or negotiate browser support. To serve a companion instead of the original, configure a compatible web-server, CDN, or image-delivery rule that:

• checks whether the WebP file exists;
• varies correctly by browser support;
• falls back to the original format;
• preserves cache separation between representations.

Do not assume that finding .webp on disk proves visitors receive it.

Verify both sides

1. Upload a JPEG or PNG after enabling Image Optimizer.
2. Confirm companions exist for the main file and expected sizes.
3. Request the normal image URL in a browser.
4. Inspect the response Content-Type and actual transferred bytes.
5. Repeat with a client that does not advertise WebP support.
6. Delete the test attachment and confirm its known companions are removed.

If files are missing, use Troubleshoot image optimization. If files exist but are not served, review the delivery layer rather than rerunning optimization.

Developer API: a single WebP for document images

An integration that needs one optimized document image can call the static helper while Image optimizer is enabled:

POM_Tweaks_Image_Optimizer::optimize_private_webp(
    string $source,
    string $destination,
    int $max_dimension = 1300
): array;

Check is_callable(array('POM_Tweaks_Image_Optimizer', 'optimize_private_webp')) before calling it. Disabling the tweak makes the API unavailable.

The source and destination are local file paths. The destination must have a .webp extension, reside in an existing directory, and not already exist. The caller must authorize the operation, use a directory with suitable access protection, and clean up its own source file. The helper does not register an attachment, update media metadata, create companion files, or delete its source.

Its document-specific contract is:

• Accept PNG, JPEG, GIF, or WebP of at most 4 MiB, 12,000 pixels per side and 40 megapixels.
• Write one WebP with its longest side at most $max_dimension, which must be between 1 and 1300. Smaller images are not enlarged.
• Use the shared Spatie image driver and optimizer chain. Conversion uses quality 85, followed by lossless WebP optimization; the smaller valid WebP is retained.
• Optimize an already conforming WebP without another lossy encoding pass, so repeated document saves do not progressively reduce its quality.
• Preserve transparency and apply supported EXIF orientation before resizing. GIF animations become a single first frame. Animated WebP and WebP containing EXIF metadata require the Imagick driver; unsupported decoding fails instead of silently changing the image.
• Require the cwebp optimizer binary. Decoder, optimizer, timeout, permission and write failures throw an exception and leave no newly created destination. An existing destination is never overwritten.

On success, the returned array contains integer width, height and bytes, plus mime equal to image/webp. Catch Throwable in the integration and report failure without retaining an unprocessed fallback. The helper removes its temporary output in all cases.

To verify an integration, process a large image, a transparent PNG and an already optimized WebP. Check the returned dimensions and MIME, repeat the WebP operation into a new destination, and confirm that an existing destination remains unchanged. This API does not change the 2560-pixel policy or companion-file behavior of normal WordPress attachment uploads.