manifest / media / wpcalibrate-image-optimizer

WPCalibrate Image Optimizer

High-performance WordPress image optimization with lossless/lossy compression, WebP/AVIF generation, background queues, and original backups.

by WPCalibrate · github.com/zeeshanraza-official/wpcalibrate-image-optimizer · website

★ 0stars

0forks

Install

No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:

wp plugin install https://github.com/zeeshanraza-official/wpcalibrate-image-optimizer/archive/refs/heads/main.zip

Readme github.com/zeeshanraza-official/wpcalibrate-image-optimizer ↗

Production-grade WordPress image optimization engineered for PHP 8.2 & 8.3.
High-performance lossless and balanced raster image compression, WebP and AVIF generation, background batch queues, original image backup & restoration, and responsive <picture> delivery.

About
Key Features
Architecture & Design
Server Requirements
Installation
Configuration & Usage
WP-CLI Commands
Hooks & Extensibility
WooCommerce Compatibility
Changelog
Support
License

About

WPCalibrate Image Optimizer is a privacy-first, zero-bloat WordPress plugin designed to reduce JPEG, PNG, and modern image sizes without compromising visual fidelity or website reliability.

Unlike solutions that send your media library to external third-party servers, all compression, resizing, and format conversions take place 100% locally on your WordPress server using native PHP ImageMagick (imagick) or GD Library (gd). No external API keys or cloud dependencies are required for local optimization.

Key Features

Local Compression Engines: Leverages ImageMagick (imagick) when available, falling back safely to GD Library (gd).
Modern Formats (WebP & AVIF): Automatic WebP generation and capability-gated AVIF generation based on runtime server codec verification.
Standards-Compliant <picture> Delivery: Wraps standard <img> tags in HTML5 <picture> containers with WebP/AVIF <source> tags. Preserves responsive srcset, sizes, lazy loading, and CSS classes with 100% original fallback safety.
Zero Frontend Overhead: No file conversion or filesystem existence checks occur during frontend page requests; delivery relies on persistent attachment metadata.
Oversized Upload Rescaling: Downscales massive digital camera uploads to administrator-configured maximum dimensions while preserving aspect ratio and preventing upscaling.
Original Backups & One-Click Restore: Unmodified originals are backed up to a protected directory (wp-content/uploads/wpcalibrate-backups/) with .htaccess and index.php guards. Restore any image at any time directly from the Media Library.
Non-Blocking Background Queue: Bulk optimization processes existing Media Library images in bounded batches (5 images/batch) with concurrency locks, crash recovery, and bounded retries. Compatible with Action Scheduler or native WP-Cron.
Animated GIF Protection: Automatically detects multi-frame GIFs and skips destructive raster processing, preventing frame flattening.
WooCommerce Ready: Fully compatible with WooCommerce product featured images, gallery images, and variation thumbnails. Declares official High-Performance Order Storage (HPOS) and Checkout Block compatibility.
Full WP-CLI Support: High-volume libraries can be scanned, queued, processed, and restored from the command line.
Enterprise Brand Isolation: Shared-parent WPCalibrate admin menu registration prevents duplicate top-level menus while keeping settings, routes, and nonces strictly isolated.
Accessibility & RTL: Accessible keyboard navigation, clear status badges (no color-only status), and native RTL stylesheet support.

Architecture & Design

WPCalibrate Image Optimizer is built with clean, modular, object-oriented PHP:

Target Environments: PHP 8.2 and PHP 8.3 (declare(strict_types=1) across all internal classes).
Unique Namespace: WPCalibrate\ImageOptimizer
Unique Prefix: wpcalibrate_imgopt_
Zero Third-Party Vendor Bloat: Powered by a custom PSR-4 autoloader with no Composer dependencies required for production runtime.
Extensible Interfaces: ImageProcessorInterface, LicenseProviderInterface, QueueInterface, and LoggerInterface enable clean future additions (e.g., cloud engines or commercial modules) without rewriting core plugin logic.

wpcalibrate-image-optimizer/
├── wpcalibrate-image-optimizer.php   # Main bootstrap & activation hooks
├── uninstall.php                    # Safe uninstaller with retention choices
├── readme.txt                       # WordPress.org standard repository readme
├── LICENSE.txt                      # GNU General Public License v2
├── branding/                        # WPCalibrate icons (dark & white)
├── languages/                       # Translation templates (.pot)
├── assets/
│   ├── css/                         # Admin CSS & RTL stylesheets
│   └── js/                          # Asynchronous admin & media library scripts
└── src/
    ├── Autoloader.php               # PSR-4 native autoloader
    ├── Plugin.php                   # Core plugin orchestrator
    ├── Admin/                       # Menu, settings tabs, assets & media UI
    ├── Bootstrap/                   # Environment checks, activator & deactivator
    ├── Compatibility/               # WooCommerce HPOS & Multisite adapters
    ├── Contracts/                   # Processor, License, Queue & Logger interfaces
    ├── Database/                    # Repeatable schema migrations
    ├── Delivery/                    # Modern format <picture> transformer
    ├── Image/                       # Imagick & GD engines, Exif & File Safety
    ├── License/                     # Provider abstraction & masked key storage
    ├── Logging/                     # Diagnostic logger with data redaction
    ├── Media/                       # Upload hooks, backup manager & bulk scanner
    ├── Queue/                       # Background worker, concurrency job locking
    ├── Support/                     # Config defaults, validator & statistics
    └── CLI/                         # WP-CLI command integration

Server Requirements

PHP: 8.2.0 or higher (fully tested on PHP 8.2 and PHP 8.3).
WordPress: 6.4 or higher (tested up to WordPress 6.7).
Image Extensions: PHP imagick extension or PHP gd extension.
Modern Codecs:
- WebP generation requires GD or Imagick built with WebP support.
- AVIF generation requires GD or Imagick built with AVIF support.
Filesystem: Write permissions within wp-content/uploads/.

Installation

Download the latest release ZIP (wpcalibrate-image-optimizer-1.0.0.zip).
Navigate to Plugins > Add New > Upload Plugin in your WordPress dashboard.
Select the ZIP file and click Install Now.
Click Activate Plugin.
Go to WPCalibrate > Image Optimizer in your WordPress sidebar to configure your settings.

Configuration & Usage

Compression Presets

Balanced (Default & Recommended): Optimal balance between small file sizes and visual fidelity (JPEG 82, WebP 80, AVIF 65, PNG level 6).
Lossless: Prioritizes visual perfection and safe metadata retention (JPEG 92, WebP 90, AVIF 85, PNG level 9).
Maximum Savings: Aggressive compression for lightweight page speed (JPEG 72, WebP 68, AVIF 50, PNG level 7).
Advanced Mode: Allows custom quality sliders (1–100) per format, custom PNG compression levels, and custom dimensions.

Modern Formats (WebP & AVIF)

Enable Generate WebP or Generate AVIF in the Modern Formats tab. When enabled, optimized images will produce companion .webp and .avif files alongside the original JPEG/PNG files.

Frontend delivery automatically serves these files using native HTML <picture> markup:

<picture class="wpcalibrate-picture">
  <source type="image/avif" srcset="https://example.com/wp-content/uploads/image.jpg.avif 1200w" sizes="(max-width: 1200px) 100vw, 1200px">
  <source type="image/webp" srcset="https://example.com/wp-content/uploads/image.jpg.webp 1200w" sizes="(max-width: 1200px) 100vw, 1200px">
  <img src="https://example.com/wp-content/uploads/image.jpg" class="size-full wp-image-10" alt="Sample" loading="lazy" />
</picture>

Automatic Upload Workflow

When Automatic Optimization is enabled, any newly uploaded image in the WordPress Media Library is automatically:

Checked for raster safety and memory budget.
Backed up to the protected backup folder (if Keep Originals is active).
Rescaled if it exceeds maximum configured dimensions.
Compressed using the active preset.
Intermediate thumbnail sizes are optimized.
WebP and AVIF files are generated.

Bulk Media Library Optimization

To optimize existing Media Library images:

Navigate to WPCalibrate > Image Optimizer > Bulk Optimization.
Click Scan & Queue Unoptimized Images.
Click Process Queue Now to monitor the live batch process via AJAX, or let WP-Cron process the queue safely in the background.

Original Backups & Instant Rollback

Backups are stored in wp-content/uploads/wpcalibrate-backups/{attachment_id}/.
To restore an individual image, open the Media Library (List view or modal) and click Restore Original.
Restoration replaces the live file with the original, cleans up derivative modern files, and regenerates thumbnails.

WP-CLI Commands

Manage your image library via command-line interface:

# View optimization statistics and server capabilities
wp wpcalibrate image-optimizer status

# Optimize an individual attachment by ID
wp wpcalibrate image-optimizer optimize --attachment=123

# Restore an attachment to its pre-optimized original
wp wpcalibrate image-optimizer restore --attachment=123

# Scan Media Library and enqueue unoptimized images
wp wpcalibrate image-optimizer bulk --limit=100

# Process pending background queue jobs
wp wpcalibrate image-optimizer queue --batch-size=20

# Retry failed queue jobs
wp wpcalibrate image-optimizer retry-failed

Hooks & Extensibility

Actions

do_action('wpcalibrate_imgopt_attachment_optimized', int $attachment_id, OptimizationResult $result);
Fired after an attachment and all its intermediate sizes are successfully optimized.

Filters

apply_filters('wpcalibrate_imgopt_register_processors', array $processors);
Register custom image processors (e.g. future cloud providers).
apply_filters('wpcalibrate_imgopt_license_provider', LicenseProviderInterface $provider);
Register a custom remote licensing verification provider.

WooCommerce Compatibility

WPCalibrate Image Optimizer is designed to work seamlessly alongside WooCommerce without making WooCommerce a required dependency:

Automatically optimizes WooCommerce product featured images, gallery thumbnails, and variation images.
Does not modify product CRUD, order data, or database tables.
Declares official compatibility for WooCommerce High-Performance Order Storage (HPOS) and Cart/Checkout Blocks.

Changelog

1.0.0 - 2026-10-07

Initial release.
ImageMagick (imagick) and GD Library (gd) local processing engines.
Lossless, Balanced, Maximum Savings, and Advanced compression presets.
WebP and AVIF generation with runtime codec capability verification.
Safe <picture> HTML delivery transformer with responsive srcset support.
Background queue with concurrency locking (JobLock), crash timeout, and retry limits.
Original image backup manager and one-click Media Library restoration.
Media Library table columns and attachment details modal integration.
Dynamic registered thumbnail size optimizer.
WP-CLI command suite (status, optimize, restore, bulk, queue, retry-failed).
Full WooCommerce HPOS compatibility declaration.
Shared-parent WPCalibrate admin menu registration with isolated settings routes.

Support

Email: support@wpcalibrate.com
Website: https://wpcalibrate.com
Marketplace: https://marketplace.wpcalibrate.com/
Phone / WhatsApp: +447474795976

License

This project is licensed under the terms of the GNU General Public License v2 or later (GPL-2.0-or-later). See LICENSE.txt for details.