ImageWoc

ImageWoc (Image WordPress Optimization & Conversion) processes images locally on your WordPress server. It can resize oversized uploads proportionally, convert supported source images to JPG, PNG, or WebP, control output quality, preserve transparency when possible, and keep one untouched backup of every original image for future reprocessing. A key feature is reference-safe bulk optimization. When an existing Media Library image is converted and its master filename or extension changes, ImageWoc keeps the same WordPress attachment ID and updates stored references from the old image URL to the new optimized URL. It also maps regenerated WordPress intermediate-size URLs where matching sizes exist. This helps prevent broken image references when optimized images are already used in posts, pages, Gutenberg blocks, page-builder data, widgets, templates, menus, links, and other content stored in standard WordPress posts, metadata, and options. Main features

• Automatic optimization during Media Library uploads.
• Global enable/disable switch without deactivating the plugin.
• Proportional resizing based on a configurable maximum long side. No cropping or distortion.
• Output conversion to JPG, PNG, or WebP.
• Configurable quality from 0 to 100.
• Preserves alpha transparency when the selected output format supports it.
• If transparent content cannot safely be saved as JPEG, the plugin uses a supported alpha-capable output instead of flattening the image.
• Keeps one untouched backup of the original uploaded file.
• WordPress generates its normal thumbnail and intermediate sizes from the optimized master image.
• If input and output formats are already the same, re-encoding is avoided unless resizing is required.
• Supports JPG/JPEG, PNG, WebP, static GIF, TIFF/TIF, BMP, AVIF, HEIC/HEIF as input when the server image libraries/codecs support them.
• Animated GIF files are skipped to preserve animation frames.
• Uses WordPress image editing APIs and the image capabilities available on the server.

Optimization Preview / Dry Run Before changing the Media Library, ImageWoc can run a read-only preview using the current settings. The preview reports how many images would change, how many would be resized or converted, and an estimated storage reduction. No image files, attachment metadata, or stored content references are modified during the preview. Automatic and manual rollback transactions Each bulk optimization run is treated as a transaction. Before an attachment is changed, ImageWoc stores a protected snapshot of its current master file, registered WordPress intermediate sizes, attachment metadata, MIME type, and reference migration map. If a processing failure occurs after the attachment has begun changing, ImageWoc attempts to restore that snapshot automatically. The administrator can also roll back the latest bulk transaction from the ImageWoc settings screen. Manual rollback restores the pre-batch image files and WordPress metadata and reverses the stored URL replacements made by ImageWoc. Rollback runs in short resumable requests rather than one long PHP request. ImageWoc Health Scanner The read-only Health Scanner checks the Media Library for common image integrity and optimization issues, including missing master files, incomplete attachment metadata, registered intermediate sizes missing from disk, missing untouched original backups, masters larger than the configured long-side limit, output-format mismatches, and unusually large master files. Findings are grouped by severity and the scanner does not modify the Media Library. Existing Media Library / bulk optimization

• Processes existing image attachments in small asynchronous requests to reduce the risk of PHP timeouts.
• Uses an attachment-ID cursor instead of large SQL OFFSET scans.
• Saves progress after each processed image.
• Pause and resume support.
• Can resume after refreshing the admin page.
• Persistent progress counters for processed, skipped, and failed items.
• Detailed downloadable log.
• Reprocesses from the untouched backup when a backup already exists.
• Keeps the original WordPress attachment ID unchanged.
• Updates old master-image URLs to the newly optimized master URL.
• Updates known old intermediate-size URLs to regenerated intermediate-size URLs.
• Handles replacements inside standard WordPress content, options, and metadata, including serialized PHP data and JSON values.
• Clears relevant WordPress caches after reference updates.
• Provides developer hooks for integrations that need to update proprietary custom tables or storage.

Stored reference updates During bulk optimization, URL replacement covers standard WordPress storage used by many themes and plugins, including:

• post content, including Gutenberg block markup stored in post_content;
• post metadata commonly used by page builders and custom fields;
• WordPress options, including widget and global configuration data;
• term metadata;
• user metadata;
• comment metadata.

The replacement layer is serialization-aware and JSON-aware. The attachment ID remains unchanged, so integrations that reference Media Library images by attachment ID continue to reference the same attachment. Third-party plugins can store image URLs in proprietary database tables or external systems. Those stores cannot be discovered safely in a generic way, so ImageWoc exposes hooks that integrations can use to extend reference migration. Original image backups Before processing an uploaded image, ImageWoc stores one untouched copy of the source file in a protected backup area under the WordPress uploads directory. WordPress-generated thumbnails are not duplicated into the backup. When an image is optimized again later, the plugin can work from this untouched source instead of recompressing a previously optimized image. This avoids cumulative quality loss when changing dimensions, output format, or quality settings. Original backups are intentionally not deleted automatically when the plugin is uninstalled, to reduce the risk of accidental loss of source files. Image format notes Available source formats depend on the image libraries and codecs installed on the web server. Formats such as TIFF, AVIF, HEIC, and HEIF commonly require Imagick/ImageMagick with the corresponding codec support. JPEG does not support alpha transparency. ImageWoc avoids destructive transparency flattening and selects an available alpha-capable format when needed.

1. Upload the plugin to WordPress or install it from the WordPress Plugin Directory.
2. Activate ImageWoc from the Plugins screen.
3. Go to Settings > ImageWoc.
4. Enable image optimization.
5. Set the maximum long side in pixels, output format, and quality.
6. Save the settings.
7. New supported uploads will be processed automatically.
8. To optimize existing Media Library files, use the bulk optimization section on the same settings page.

Before running bulk optimization on an established production site, a complete site/database backup is recommended because existing stored image URLs may be updated.

0.6.0

• Added Optimization Preview / Dry Run with estimated resize, conversion, and storage impact.
• Added transaction snapshots for automatic recovery during bulk optimization failures.
• Added manual rollback of the latest bulk optimization transaction, including files, metadata, MIME type, and stored URL reference reversal.
• Added the read-only ImageWoc Health Scanner with severity-based diagnostics.
• Kept all new long-running operations asynchronous and resumable through short requests.

0.5.1

• WordPress.org compliance fixes for filesystem operations, prepared SQL identifiers, caching annotations, and readme metadata.

0.5.0

• Prepared the plugin metadata and readme for WordPress.org Plugin Directory submission.
• Changed all administrator-facing and runtime messages to English.
• Added GPLv2-or-later license metadata and WordPress.org compatibility metadata.
• Documented reference-safe bulk optimization and supported reference storage in detail.
• Retains the 0.4.0 reference migration, resumable bulk processing, original backups, conversion, resizing, transparency handling, and global enable/disable functionality.