Kitgenix Image Optimizer

Kitgenix Image Optimizer is a local WordPress image optimization plugin for compressing Media Library images, resizing oversized uploads and creating modern WebP or AVIF sidecar files without sending image files to a remote compression API. Image processing runs through WordPress's WP_Image_Editor layer using the image library available on the server, normally GD or Imagick. New uploads can be optimized automatically, while existing media can be processed through a persistent background queue or WP-CLI. The plugin is designed for WordPress sites and WooCommerce stores that want image compression, size reduction and modern-format delivery without per-image credits or an external image-processing account. Learn more about Kitgenix at Kitgenix. WordPress Image Optimization Features

• Local JPEG, PNG, WebP, GIF and AVIF optimization when supported by the active WordPress image editor.
• Automatic optimization after WordPress generates attachment metadata and registered image sizes.
• Persistent bulk queue for existing Media Library images.
• Bulk optimize or force re-optimize modes.
• Pause, resume, stop and retry-failed queue controls.
• WP-Cron background continuation so the browser does not need to remain open.
• Compression presets plus custom JPEG, PNG, WebP and AVIF quality controls.
• Maximum width/height integration with WordPress's big_image_size_threshold behaviour.
• Optional WebP and AVIF sidecar generation for JPEG/PNG source images.
• Frontend <picture> delivery when corresponding sidecars exist.
• Optional metadata stripping.
• Optional optimization of generated thumbnails/sub-sizes.
• Optional original-image backups and restore workflow.
• Optional native loading attribute management for frontend images.
• Animated GIF protection.
• Exclusions by MIME type, file size, dimensions, filename pattern, attachment ID and uploads-relative directory.
• File/pixel/memory safety checks before expensive image decoding.
• Atomic file replacement to reduce corruption risk if processing is interrupted.
• "Do not replace with a larger file" protection.
• Media Library status/savings information and per-image actions.
• Aggregate optimization statistics with manual recalculation.
• Diagnostics and WordPress Site Health integration.
• Capped local activity/error log.
• REST capability/status endpoints.
• WP-CLI commands for optimization, queue control, status, statistics and restore.

Local Processing: No Image Optimization API Required The source image and generated image files remain on the WordPress server. The optimizer asks WordPress for an appropriate image editor, processes the file locally and writes the result back to the uploads directory. There is no Kitgenix compression service and no requirement to upload images to a third-party optimization API. That avoids per-image quotas and keeps the actual image-processing data flow within the site/hosting environment. Automatic Upload Optimization When automatic optimization is enabled, the plugin hooks into WordPress attachment-metadata generation after WordPress has created registered image sizes. This lets the plugin work with the final master/sub-size set rather than racing the core thumbnail-generation process. Per-file fingerprints are used so regenerating attachment metadata does not automatically mean every unchanged file must be recompressed again. Compression Presets and Custom Quality Administrators can choose a preset compression profile or use custom format settings. The code supports configurable JPEG quality, PNG compression level, WebP quality and AVIF quality, subject to what the server's active image editor can actually encode. Modern-format options are capability-gated. If WordPress reports that the active server/editor cannot encode WebP or AVIF, the relevant functionality is not treated as available simply because a checkbox exists. WebP and AVIF Sidecars For JPEG/PNG source images, optional .webp and .avif sidecars can be generated alongside the original file. The original source remains the fallback. When sidecar delivery is enabled and the corresponding sidecar files exist, frontend image markup can be wrapped in a <picture> element containing AVIF and/or WebP <source> elements. AVIF is placed before WebP where both are available so a capable browser can choose the first supported modern format. The delivery logic only rewrites images that resolve within the site's WordPress uploads directory. Remote images are not rewritten as if local sidecar files existed. Resizing Oversized Images Configured maximum dimensions integrate with WordPress's big-image threshold so the site does not unnecessarily perform one resize in WordPress core and a second independent resize in the plugin. The optimizer preserves aspect ratio and relies on the active WordPress image editor for the actual image operation. Metadata Stripping Optional metadata stripping can remove image metadata during processing where supported by the active editor. This can reduce file size and may remove embedded EXIF/GPS information from images that are rewritten. Because metadata requirements differ between sites, administrators should keep this disabled if they need embedded camera/copyright/location metadata to remain in optimized derivatives. Backups and Restore If Backup Originals is enabled before optimization, the plugin can retain an original backup file. A per-image restore action and WP-CLI restore command can put that backup back in place. Restoring a master image regenerates WordPress attachment metadata and sub-sizes so the database dimensions and generated files stay aligned with the restored source. Backup deletion on uninstall is separately configurable. Media Library originals are never treated as disposable plugin settings data. Bulk Optimization Queue Large libraries are handled through persisted queue state rather than one giant admin request. The queue can be started in normal bulk mode or re-optimization mode, paused, resumed, stopped and asked to retry failed items. Because it acts on every image in the library, the bulk queue is available to administrators only (manage_options); users who can upload files can still optimize or restore their own images individually. A scheduled background runner continues processing queue batches after the administrator leaves the page. The admin interface can poll queue status and display processed/failed counts without requiring one PHP request to remain open for the entire library. Exclusion Rules The code includes exclusions for:

• Files below a minimum size.
• Files above a maximum size.
• Filename patterns.
• MIME types.
• Minimum width/height thresholds.
• Maximum width/height thresholds.
• Specific attachment IDs.
• Upload-directory path fragments.

Animated GIFs can also be skipped to avoid destroying animation during normal still-image processing. Image Safety and Atomic Writes Before decoding an image, the guard can consider file size, pixel dimensions and estimated memory requirements. This is intended to reject obviously unsafe or resource-exhausting image inputs before GD/Imagick attempts a costly decode. Optimized output is written to a temporary file and verified before it replaces the existing file. If the newly generated file is not actually smaller than the original, the optimized candidate can be discarded so "optimization" does not make the asset larger. Lazy Loading An optional frontend lazy-loading layer can add native loading attributes to <img> elements that do not already declare one. The first image is left eager to avoid automatically delaying the likely Largest Contentful Paint candidate, while later images can receive loading="lazy". The lazy-loading processor skips admin and other unsuitable contexts and does not overwrite an existing loading attribute. Media Library and Attachment Tools The Media Library receives optimization status/savings information and per-image controls. An attachment panel provides additional context for a selected image, and administrators can trigger single-image optimization or restore where permitted. Side-by-Side Compression Preview The "Compare Compression" button lives in the "Image Optimizer" box on an image's full Attachment Details edit page (post.php?post=<id>&action=edit) - not in the quick preview that opens when you click a thumbnail in the Media Library's grid view. To reach it: in the Media Library, switch to List view and click the file's name (or "Edit"), or from the grid view's quick preview click "Edit more details"/"Edit Image" first. Either route lands you on the same edit page, with the Image Optimizer box and its Compare Compression button in the sidebar. Open it to see the current file next to a preview at each compression level: Conservative, Balanced, Aggressive and Maximum. Each preview shows the resulting file size and saving. You can zoom to 100% with both images scrolling together to check fine detail. When you're happy, optimize the image with the level you chose. This applies to that image only and does not change your global setting. Previews are encoded exactly as the real optimization would be, and nothing is changed until you commit. Temporary preview files are deleted automatically after an hour. AJAX actions require both the plugin-level media capability and permission to edit the individual attachment. Diagnostics and Site Health Diagnostics report GD/Imagick availability and versions, preferred WordPress image editor, PHP memory information and encode/decode support for relevant formats. Site Health exposes the same capability picture and can warn when a feature such as WebP/AVIF conversion is enabled but the server cannot perform that conversion. Optimization failure counts and queue status are also available for troubleshooting. REST API The plugin registers authenticated/read-only diagnostic routes under: kitgenix-image-optimizer/v1 Routes provide status and capability information. They are intended for administration/diagnostics rather than remote image upload or third-party compression. WP-CLI The command base is: wp kitgenix-optimizer The code includes commands for server/queue status, optimizing all eligible images or a single attachment, forced re-optimization, statistics, backup restore and queue actions (start, pause, resume, stop, retry, status). Privacy and Storage Images are processed locally. Plugin settings, queue state, statistics, logs and per-image optimization metadata are stored in WordPress. Optional backup and sidecar files are stored in the site's uploads area. The shared Kitgenix admin Hub can request public plugin-directory data from WordPress.org, and the admin stylesheet imports disclosed Google Fonts. Neither service receives image files for optimization. Typical Uses

• Reduce image file sizes on a content-heavy WordPress site.
• Optimize WooCommerce product imagery without a per-image SaaS plan.
• Convert supported JPEG/PNG uploads to WebP/AVIF sidecars.
• Process an existing Media Library in resumable batches.
• Preserve recoverability by creating local original backups before optimization.
• Diagnose whether a host can actually encode WebP or AVIF.
• Automate image maintenance with WP-CLI.

2.2.0 (30 October 2026)

• Fix: Deleting a media attachment now also removes its .webp/.avif sidecars and -kitgenix-original backup file, for the main file and every registered size. Previously these were never cleaned up, so disk usage from optimised sites grew without bound as media was deleted. Editing an image with WordPress's built-in editor (crop, rotate or scale) now also removes sidecars/backups left over from sub-sizes the edit replaced, and regenerates sidecars for the edited result when "Auto-Optimize on Upload" is enabled.
• New: Added a "Clean orphaned sidecar & backup files" tool (Images tab) and a wp kitgenix-optimizer clean-orphans WP-CLI command, to find and remove .webp/.avif sidecars and -kitgenix-original backups left behind by attachments deleted before this release, or by files removed outside WordPress's own deletion flow.
• Fix: Featured images rendered through post_thumbnail_html were wrapped in a <picture> element twice – once by the wp_get_attachment_image filter that wp_get_attachment_image() already applies internally, and a second time by this plugin's own post_thumbnail_html hook on top of that already-wrapped markup, producing invalid nested <picture><picture>...</picture></picture> output. The redundant post_thumbnail_html hook has been removed; featured images continue to get modern-format sources through the existing wp_get_attachment_image filter.
• Fix: An <img> tag a theme, block or page builder had already placed inside its own <picture> element was wrapped a second time when it appeared in post content, for the same reason. Content image wrapping now skips any <img> that already sits inside an existing <picture>...</picture> block.
• New: Side-by-Side Compression Preview. A "Compare Compression" button on the attachment edit screen shows the current image beside a preview at each compression level (Conservative, Balanced, Aggressive, Maximum, and Custom when selected). Each preview shows its file size and saving, with Fit/100% zoom and synced scrolling. You can then optimise with the chosen level for that image only, without changing the saved Compression Level. Previews use the same resize, metadata and quality pipeline as real optimisation, so the size shown is what you get, and nothing changes until you commit. Temporary preview files are removed automatically after an hour and on uninstall.
• Security: The bulk optimisation queue actions (start, re-optimise, pause, resume, stop, retry and status) now require the manage_options capability. Previously any user who could upload files, including Authors, could start a site-wide bulk re-optimisation that recompressed other users' media.
• Security: The /kitgenix-image-optimizer/v1/capabilities REST endpoint, which reports the server's exact GD and ImageMagick versions, is now restricted to administrators.
• Fix: The Image Optimizer stats bar on the Media Library screen now sits below the "Media Library" heading, like other admin notices, instead of being wedged between the admin bar and the page heading by a fixed top margin.
• Fix: The Media Library screen no longer loses WordPress's standard left gutter. The shared Kitgenix admin stylesheet removed the gutter on every screen that loaded it, so the page heading, stats bar and media table sat flush against the admin menu. It is now only removed on Kitgenix's own settings screens.
• Improved: Raised the minimum PHP version to 8.2 (Requires PHP: 8.2).
• Improved: Tested up to WordPress 7.4, and reviewed for compatibility with PHP 8.2 to 8.5. The full codebase passes syntax checks on PHP 8.5 and a PHPCompatibility scan for PHP 8.2–8.5, and uses no dynamic properties or functions deprecated in PHP 8.2–8.5.
• Dev: Moved the resize, metadata-stripping and quality steps into a shared Optimizer::prepare_editor() so previews and real optimisation always use the same pipeline. Added Optimizer::with_compression_level() to run an optimisation with a one-off preset. The single-image optimise AJAX action now accepts an optional compression_level.
• Dev: Corrected a WordPress coding-standards (PHPCS) escaping annotation on the log-retention form; wp_nonce_field() output is already escaped by WordPress core, so this is a no-op code-quality fix.
• Dev: Removed the PluginScore verification code from the readme, as Kitgenix Plugin Score has been discontinued.
• Dev: Bumped the version to 2.2.0 across the plugin.
• Documentation: Added the Side-by-Side Compression Preview to the readme and developer documentation, including the new kitgenix_image_optimizer_preview_compression AJAX action and kitgenix_image_optimizer_cleanup_previews cron hook.
• Documentation: Regenerated the .pot translation template for 2.2.0.
• Documentation: The readme changelog now lists only the current release. The full release history is in CHANGELOG.md.

Full release history is available in the plugin's CHANGELOG.md file.