XC Image Optimizer — Complete Guide

1

Requirements

XC Image Optimizer runs entirely on your server — no external image processing services are needed. Make sure your hosting environment meets the following requirements before installing.

🟦

WordPress

Version 5.6 or higher

✔

🐘

PHP

Version 7.4 or higher

✔

🔧

GD or Imagick

At least one PHP image library

✔

🔐

OpenSSL

Recommended — for license key encryption

★

ℹ️

Imagick vs. GD Imagick generally provides better compression quality and supports more edge cases. GD is a widely available fallback. The plugin will automatically use the best available library, or you can set a preference in Settings → Advanced.

Optional: WebP & AVIF Support

Format conversion to WebP or AVIF requires that your PHP image library was compiled with the appropriate encoder support. The plugin's dashboard automatically detects and reports which conversions are available on your server.

Format	Imagick requirement	GD requirement
WebP	Imagick compiled with libwebp	GD compiled with libwebp
AVIF	Imagick compiled with libavif (ImageMagick 7.0.25+)	GD 2.1.0+ with libavif

💡

Checking your server After installation, navigate to Image Optimizer → Dashboard. The "Server Capabilities" section shows which libraries and formats are available in a glance — no manual phpinfo() required.

2

Installation

Manual Upload (Recommended)

Download the plugin ZIP Download xc-image-optimizer-1_0_0.zip from XaniaCode.
Upload to WordPress In your WordPress admin go to Plugins → Add New → Upload Plugin, choose the ZIP file and click Install Now. Alternatively, unzip and upload the xc-image-optimizer/ folder to /wp-content/plugins/ via FTP.
Activate the plugin Go to Plugins → Installed Plugins and click Activate next to XC Image Optimizer. The plugin verifies your PHP and WordPress version at activation time and will show a notice if the requirements are not met.
Activate your license (or start the trial) Navigate to Image Optimizer → 🔑 License. Enter your license key or click Start Free Trial to begin a 14-day evaluation period.
Configure your settings Go to Image Optimizer → Settings and adjust compression level, target format, and bulk options to suit your site. The defaults are safe and suitable for most sites.
Run bulk optimization Go to Image Optimizer → Bulk Optimize, choose a mode (Compress, Convert, or Both), and click Start Optimization.

⚠️

Shared Hosting Note If your host enforces a strict execution timeout (e.g., 30 seconds), use a small batch size (1–3) and a delay of 1000 ms or more between batches. The built-in WP-Cron fallback will continue processing even after the browser tab is closed.

3

Licensing

XC Image Optimizer uses the XaniaCode License Manager to manage access. A valid license is required for full use of all features beyond the free trial period.

Free Trial

A 14-day free trial starts automatically when you first activate the plugin. No payment or credit card is required to begin. All features are fully available during the trial.

Activating a License Key

Obtain your key — Purchase a license from xaniacode.com and copy your license key from the order confirmation email or your account dashboard.
Open the License page — In WordPress admin, go to Image Optimizer → 🔑 License.
Enter and activate — Paste your key in the field and click Activate License. The plugin communicates with the XaniaCode licensing server via a secure POST request — the key is never exposed in server logs or browser history.

Key Facts About the Licensing System

Encrypted storage

Your license key is stored encrypted in the WordPress database (AES-256-CBC with HMAC), not in plain text.

Automatic verification

The plugin performs background license checks twice daily via WP-Cron, independently of admin visits.

Deactivation

When you deactivate a license, the remote server is notified before local state is cleared, preventing stranded activations.

Data recovery

Restore originals and delete backups always work — even after license expiry. Your images are never held hostage.

Optional constant

Add define('XC_LICENSE_ENC_KEY', 'your-key'); to wp-config.php to stabilize the encryption key across WordPress auth salt rotations.

💡

After license expiry: Bulk optimization and new optimizations will pause, but all previously optimized images remain optimized, and backup restore/deletion always remain available.

4

Settings — Compression

Access compression settings at Image Optimizer → Settings → 🗜️ Compression.

Auto-compress on Upload

Default: enabled

When enabled, every image uploaded through the WordPress Media Library is automatically compressed immediately after upload. Disable if you prefer manual control or run scheduled bulk jobs instead.

Compression Level

Default: balanced

Three modes available:

Lossless — Minimal size reduction with no perceptible quality loss. Best for logos and graphics with flat colors.
Balanced — Recommended for most sites. Good savings with imperceptible quality change for photographs.
Aggressive — Maximum file-size reduction. May introduce very slight quality loss on high-frequency detail. Best reviewed before deploying site-wide.

JPEG Quality

Default: 82

Sets the JPEG encoder quality value (1–100). Values between 75 and 90 are the recommended sweet spot. Lower values produce smaller files at the cost of more visible artifacts; higher values produce larger files with near-original quality.

Max Width / Height

Default: 2560 × 2560 px

Images larger than these dimensions are automatically downscaled during compression, preserving aspect ratio. Set either value to 0 to disable the corresponding cap. Useful for enforcing maximum dimensions site-wide without a separate resize plugin.

Strip Metadata

Default: enabled

Removes EXIF, IPTC, and ICC color profile data from images. This reduces file size and removes potentially sensitive information (GPS coordinates, camera model, etc.). Disable only if your workflow depends on embedded metadata being preserved.

Keep Original Backup

Default: enabled

Before overwriting the original image, the plugin saves a copy with the .iop-backup extension in the same directory. This allows you to restore the original at any time. Backups consume additional disk space; manage them from the Tools page.

Skip Files Smaller Than

Default: 10 KB

Images below this threshold in kilobytes are skipped. Very small images typically have negligible savings, and compression overhead could outweigh benefits. Set to 0 to process every image regardless of size.

Skip Animated GIFs

Default: enabled

Animated GIFs contain multiple frames. Compressing them as static images destroys the animation. With this option enabled, animated GIFs are automatically detected and bypassed during both compression and conversion operations.

ℹ️

Smart rollback: If the compressed output is actually larger than the original file, the plugin automatically discards the compressed version and keeps the original. Your images will never get bigger.

5

Settings — Format Conversion

Access conversion settings at Image Optimizer → Settings → 🔄 Format Conversion. If neither WebP nor AVIF is available on your server, the plugin displays a notice and conversion options are disabled.

Auto-convert on Upload

Default: disabled

When enabled, JPEG, PNG, and GIF images are converted to the selected next-gen format immediately on upload. Disabled by default — enable only after confirming your server supports the target format.

Target Format

Default: webp

Choose between WebP (wider browser support, excellent compression) or AVIF (best compression, cutting-edge format, requires modern browsers). The dashboard indicates which formats are available on your server.

WebP Quality

Default: 82

Quality slider (1–100) for WebP output. Values of 75–85 provide a good balance between file size and visual quality.

AVIF Quality

Default: 60

Quality slider (1–100) for AVIF output. AVIF achieves excellent quality at lower numeric values compared to JPEG — values of 50–70 typically produce visually excellent results.

Keep Original After Convert

Default: enabled

Keeps the original JPEG/PNG file alongside the converted WebP/AVIF file. The original is never deleted during conversion. This is the safe default — disable only if disk space is critical and you are confident in conversion quality.

Serve Next-Gen Automatically

Default: enabled

When enabled, WordPress automatically rewrites image URLs (including srcset responsive image sets) to point to the converted WebP/AVIF file when it exists on disk. Works with CDNs, custom upload directories, multisite, and mixed HTTP/HTTPS setups. Browsers that do not support the format will fall back gracefully via HTML <picture> element if implemented in the theme.

💡

Size rollback: If the converted file is larger than the original, it is automatically discarded. Same-format conversions (e.g., WebP → WebP) are detected and skipped entirely.

6

Settings — Bulk Processing

Access bulk settings at Image Optimizer → Settings → ⚡ Bulk Processing. These settings control how the background queue processes your image library.

Batch Size

Default: 5 images/request

Number of images processed per AJAX request during bulk optimization. Smaller values (1–3) are safer on shared hosting with tight execution limits. Larger values (10–20) are faster on VPS/dedicated servers with higher resource limits. Recommended: 3–5 for most sites.

Delay Between Batches

Default: 500 ms

Pause (in milliseconds) added between each batch request. Adds a brief breathing room between processing bursts to reduce instantaneous CPU load on the server. Increase to 1000–2000 ms on resource-constrained hosting. Set to 0 for maximum throughput on powerful servers.

7

Settings — Advanced

Access advanced settings at Image Optimizer → Settings → 🔧 Advanced.

Preferred Processing Library

Default: auto

Forces the plugin to use a specific PHP image library:

Auto — Uses the best available library (Imagick preferred over GD).
Imagick — Force Imagick. Shows "not available" if not installed.
GD — Force GD. Useful for debugging or if Imagick causes issues.

Skip Rules

In addition to the skip settings in the Compression panel, you can exclude specific WordPress registered image sizes from processing. This is useful when you want to optimize full-size images and large thumbnails but leave smaller derivatives untouched.

Skip sizes are configured programmatically (or left empty to process all sizes). Common size names include: thumbnail, medium, medium_large, large, full.

8

Dashboard

The Dashboard is your optimization command center. Navigate to Image Optimizer in the WordPress admin sidebar to reach it.

What You'll See

🖼️

Total Images

Total attachments in your Media Library

✅

Optimized

Images already processed

⏳

Pending

Images awaiting optimization

💾

Total Savings

Cumulative bytes saved across all images

The dashboard also displays an optimization progress bar, a Server Capabilities panel (showing Imagick, GD, WebP, AVIF availability, PHP version, memory limit, and max execution time), Quick Action links to the main plugin pages, and a Recent Optimizations table showing the last 8 processed images.

ℹ️

If any images are pending, the dashboard shows a direct button to start bulk optimization from the progress bar.

9

Bulk Optimize

Navigate to Image Optimizer → ⚡ Bulk Optimize to process your entire Media Library in the background.

Modes

Mode	What it does
🗜️ Compress Only	Applies compression to images that have not been compressed yet. Skips images already optimized.
🔄 Convert Only	Converts JPEG/PNG/GIF to the selected next-gen format (WebP or AVIF). Skips already-converted images.
⚡ Compress + Convert	Performs both operations in a single pass for maximum optimization. Most thorough option.

Controls

Start Optimization — Begins processing the queue using the selected mode.
Pause — Temporarily halts processing after the current batch completes. Click Start again to resume.
Reset All Data — Clears all optimization metadata, resetting every image to "pending" status. Does not restore original images or delete backups — use the Tools page for that.

Live Progress

While processing runs, a live progress bar updates in real time showing:

✅ Succeeded — Images successfully optimized
❌ Failed — Images that encountered an error (typically due to library limitations)
⏭ Skipped — Images skipped by configured rules (too small, animated GIF, already converted)
💾 Savings — Running total of bytes saved so far

Background Processing (WP-Cron)

If you close the browser while bulk optimization is running, the plugin's WP-Cron fallback automatically continues processing the queue every minute. A concurrency lock prevents duplicate processing even if multiple browser tabs or cron triggers fire simultaneously.

Optimization History

The lower section of the Bulk Optimize page shows the last 100 optimization log entries, including file name, original size, optimized size, savings (bytes + percentage), format conversion, status, and timestamp.

10

Media Library Integration

XC Image Optimizer integrates directly into the WordPress Media Library list view, adding per-image optimization status without requiring you to leave the media screen.

Status Column

A dedicated Optimization column appears in the Media Library list. It shows one of the following for each image:

Badge	Meaning
⏳ (pending)	Image has not been optimized yet. Click the badge to trigger optimization for that image immediately.
✅ X% saved	Image has been compressed. Shows the percentage file-size reduction.
🔄 Converted	Image has been converted to a next-gen format.
⏭ Skipped	Image was skipped due to a configured skip rule (animated GIF, minimum size, excluded size, etc.).

Attachment Meta Box

When editing a single image (Media → Edit), a dedicated meta box appears showing:

Per-size file sizes (thumbnail, medium, large, full, etc.)
Backup status for each size
Action buttons: Compress, Convert, and/or Both — shown depending on your configuration and server capabilities
Restore original button (when a backup exists)

11

Tools & Diagnostics

Navigate to Image Optimizer → 🛠️ Tools for maintenance utilities and diagnostic information.

🗂️ Backup Manager

Displays the count and total disk usage of all .iop-backup files stored in your uploads directory. Once you are satisfied with the optimization results, use the Delete All Backups button to free up disk space. This action is permanent and requires confirmation.

📋 Optimization Log

View the complete optimization history table with all processed images. Two actions are available:

Export to CSV — Downloads a CSV file with the full log for spreadsheet analysis or record-keeping.
Clear Log — Removes all log history entries. This does not reset optimization metadata (images remain marked as optimized).

⚠️

Clear Log vs. Reset All: "Clear Log" only removes the historical records table. "Reset All" (on the Bulk page) wipes optimization metadata, causing all images to reappear as pending. These are distinct operations — do not confuse them.

🧪 Test Single Image

Enter an attachment ID and choose a mode (Compress, Convert, or Both) to test the optimization pipeline on a single image without running a full bulk job. Useful for verifying settings or diagnosing issues with a specific image. Requires an active license.

🖥️ System Information

A copyable diagnostic block showing your complete server environment: PHP version, WordPress version, active image library, Imagick/GD capabilities, WebP/AVIF support, memory limit, max execution time, and license status. Use this when contacting support.

12

REST API

XC Image Optimizer exposes nine REST API endpoints under the namespace /wp-json/iop/v1/. All endpoints require the WordPress manage_options capability (administrator role). Authenticate using Application Passwords or cookie-based nonce authentication.

Method	Endpoint	Description
GET	`/stats`	Returns global optimization statistics: total images, optimized count, pending count, total savings in bytes, and savings percentage.
GET	`/pending`	Returns the count and a sample of attachment IDs that have not yet been optimized. Useful for external scheduling.
POST	`/batch`	Processes one batch of images. Accepts `offset` (integer) and `mode` (`compress`, `convert`, or `both`) in the request body.
POST	`/optimize/{id}`	Optimizes a single attachment by its WordPress attachment ID. Returns the optimization result including savings.
POST	`/restore/{id}`	Restores the original backup for the specified attachment ID. Always available, even after license expiry.
GET	`/settings`	Retrieves the current plugin settings as a JSON object.
PUT	`/settings`	Updates settings. Supports partial JSON payloads — only the keys provided are updated; all other settings remain unchanged.
GET	`/log`	Returns paginated optimization log entries. Supports `page` and `per_page` query parameters.
DELETE	`/reset`	Clears all optimization data: log table contents and optimization metadata for all attachments. Use with caution.

Example: Get Statistics

# Using curl with Application Password authentication
curl -X GET \
  https://yoursite.com/wp-json/iop/v1/stats \
  -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx"

Example: Optimize a Single Image

curl -X POST \
  https://yoursite.com/wp-json/iop/v1/optimize/123 \
  -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx"

Example: Update Settings (Partial)

curl -X PUT \
  https://yoursite.com/wp-json/iop/v1/settings \
  -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"compression_level":"aggressive","bulk_batch_size":3}'

ℹ️

Partial settings updates are safe. Sending only a subset of settings via PUT will not reset untouched keys to their defaults — only the provided keys are modified.

13

WP-CLI

All optimization operations are available via WP-CLI, ideal for server-side automation, cron jobs, and CI/CD pipelines. All commands run under the wp iop namespace.

wp iop stats Show global optimization statistics

wp iop check Report server capabilities (Imagick, GD, WebP, AVIF)

wp iop optimize Optimize all pending images (default: compress mode)

wp iop optimize --mode=both Compress + convert all pending images

wp iop optimize 123 456 789 Optimize specific attachment IDs only

wp iop optimize --dry-run Preview what would be processed without making changes

wp iop restore 123 Restore original backup for attachment ID 123

wp iop reset --yes Clear all optimization data (no confirmation prompt)

Recommended CLI Workflow for Large Sites

# 1. Check server capabilities first
wp iop check

# 2. Preview what will be processed
wp iop optimize --dry-run

# 3. Run a full compress + convert pass
wp iop optimize --mode=both

# 4. Review final stats
wp iop stats

💡

Scheduled optimization: Add wp iop optimize --mode=both --path=/var/www/html to a server cron job to automatically optimize newly uploaded images on a schedule, independent of the WordPress admin interface.

14

Uninstallation

Deleting the plugin through Plugins → Installed Plugins → Delete triggers the uninstall routine, which performs the following cleanup automatically:

Database table

The iop_log table is dropped from the WordPress database.

Attachment metadata

All custom post meta keys (_iop_compressed, _iop_converted, _iop_savings) are removed from every attachment.

Plugin settings

All plugin options, queue state, and license data are removed from the wp_options table.

Backup files

All .iop-backup files in the uploads directory are permanently deleted.

🚨

This is irreversible. If you want to keep your original images, restore them from backups via the Tools page before deleting the plugin. Once the plugin is deleted, backup files are removed automatically.

ℹ️

Deactivating the plugin (without deleting) does not remove any data. All settings, log entries, and backup files are preserved until the plugin is permanently deleted.

15

Security & Data Integrity

XC Image Optimizer is built with multiple layers of security and data-integrity safeguards.

Nonce + capability checks

Every AJAX and REST API endpoint verifies both a WordPress nonce and the manage_options capability — including read-only endpoints. Nonces are only localized to the plugin pages that require them.

Backup-first compression

The plugin verifies that a backup copy was successfully written to disk before overwriting the original. If the backup fails, the original is not touched.

No deletion on conversion

Converting an image to WebP or AVIF never deletes the original source file. The original is always preserved.

Size rollback on both operations

If a compressed or converted file is larger than the original, it is automatically discarded and the original is restored. Your images can only get smaller.

Throwable catching

All Imagick and GD calls are wrapped in Throwable catches (not just Exception), preventing fatal PHP errors from crashing the site during image processing.

Attachment-ID-based logging

Log entries are keyed on attachment ID rather than filename, preventing cross-attachment log contamination when files are renamed or replaced.

Library availability checks

function_exists() is called before every GD encoder/decoder invocation. If no image library is available, the operation returns a clean error instead of crashing.