=== ImageCompressionAI Media Optimizer ===
Contributors: rachidaitouaissi
Tags: image compression, optimize images, compress, performance, media library
Requires at least: 5.6
Tested up to: 7.1
Requires PHP: 7.2
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Compress your media library through the imagecompression.ai API. Automatic on upload, bulk compression, resizing, backups with one-click restore.

== Description ==

ImageCompressionAI Media Optimizer connects your site to the imagecompression.ai API to shrink your images without a visible quality loss. Smaller images mean faster pages, better Core Web Vitals and less bandwidth.

All the work happens on the API. Your server never runs image processing, so there is no GD or Imagick load, no memory spikes and no slow uploads, which makes this safe on shared hosting.

= Compression =

* **Three modes** - Lossy (smallest files), Lossless (no quality change) and Smart (picks per format: PNG/GIF lossless, JPEG/WebP lossy).
* **Automatic compression on upload** - every new image is queued and compressed in the background, so uploading never waits on the API.
* **Bulk compress your existing library** - a live progress bar with pause, resume and start-over. It processes one image at a time with a cursor, so it uses the same small amount of memory whether you have 50 images or 50,000.
* **Resize oversized images** - scale the full-size image down to a maximum width before compressing. Thumbnails are never resized, so your theme's layouts stay intact.
* **Strip EXIF and metadata** for extra savings.
* **Thumbnails included** - every registered thumbnail size is compressed too, not just the original.

= Control over what gets compressed =

* **Choose which thumbnail sizes** to compress, or exclude the ones your theme does not use.
* **Skip small images** - set a minimum file size, since tiny files are usually already efficient and still cost quota.
* **Skip by file name** - exclude any image whose name contains words you choose (for example logo, icon, keep-original), so images you want untouched stay untouched.

= Backups and restore =

* **Automatic backups** - the original is copied to a protected folder before it is replaced.
* **One-click restore** returns an image to exactly how it was.
* **Space-saving mode (default)** - backs up only the full-size original and rebuilds the thumbnails when you restore, which roughly halves the disk space backups use. Turn it off if you need every thumbnail file kept byte-for-byte.
* **Configurable retention** - keep backups for 3, 7 or 15 days, then they are cleaned up automatically.
* **Before and after comparison** - see the original and the compressed version side by side, with a per-size breakdown showing exactly what each thumbnail saved. These figures are stored permanently, so they remain visible even after the backup files expire.

= Visibility =

* **Dashboard** - total space saved, average reduction, how much of your library is covered, and a live quota bar.
* **Activity log** - the most recent compression requests with status, sizes before and after, percentage saved, number of thumbnails, how long it took and when. Failed and skipped attempts are logged too, with a plain-English reason, so it is easy to see why something did not compress.
* **Media Library integration** - a Compression column in the list view and a panel on the attachment edit screen showing that image's full breakdown.
* **Quota and usage** - your plan, images remaining this cycle, renewal date and lifetime totals.

= Built to stay out of trouble =

* **Integrity checks before writing** - a compressed result is verified against the file that was sent before it replaces anything, so a mismatched result can never overwrite the wrong image.
* **Never writes a larger file** - if compression would not help, the original is left alone.
* **Handles running out of quota gracefully** - compression pauses, tells you what happened, and resumes on its own once you top up. Nothing is lost and nothing is compressed twice.
* **Respects rate limits** - backs off and retries rather than hammering the API.
* **Non-destructive uninstall** - removing the plugin keeps your backups and the record of what has already been compressed, so a reinstall never re-compresses your library.

You need an API token from https://imagecompression.ai. One token binds to one domain.

== External services ==

This plugin connects to the imagecompression.ai API to compress your images. It is required for the plugin to function.

The plugin sends the following to https://imagecompression.ai:

* The public URL of each image to be compressed, so the API can fetch it.
* Your site URL, to bind your token to your domain and prevent token sharing.
* Your API token, to authenticate the request.
* Your chosen compression options (mode, maximum width, whether to strip metadata).

The API returns a temporary download link for each compressed image, which the plugin downloads and uses to replace the original file. Compressed files are deleted from the API server immediately after download.

Service provided by imagecompression.ai: terms https://imagecompression.ai/terms , privacy policy https://imagecompression.ai/privacy

== Installation ==

1. Upload the plugin to `/wp-content/plugins/` or install it from the Plugins screen.
2. Activate it.
3. Go to **ImageCompressionAI Media Optimizer > Settings**, paste your API token and click **Activate**.
4. Choose your compression options.
5. Optionally go to **Bulk Compress** to process images you already have.

New uploads are compressed automatically from that point on.

== Frequently Asked Questions ==

= Where do I get a token? =

From your account at imagecompression.ai. It looks like `ic_live_` followed by 32 characters.

= Does this slow down my site or my uploads? =

No. All image processing happens on the API, not your server. Uploads are queued and compressed in the background, so the upload itself never waits.

= Can I move my token to another site? =

Yes. Use **Deactivate this site** on the Settings page first, then activate it on the new site.

= Are my originals safe? =

With backups enabled, every original is copied to a protected folder before it is replaced, and can be restored with one click until the retention window passes. The backup is taken before any resizing, so a restore always returns the true full-resolution original.

= How is quota counted? =

Per file, including thumbnails. One image with five thumbnail sizes costs six. You can lower that cost by excluding thumbnail sizes you do not use, or by skipping small images.

= What happens if I run out of quota part-way through? =

Compression pauses and tells you exactly what happened. Nothing is left half-done: the API processes an image all-or-nothing, so you never end up with a compressed original and uncompressed thumbnails. Once you top up or renew, it resumes on its own, and you can also resume it manually from the notice.

= Will it compress the same image twice? =

No. Every compressed image is flagged, and bulk runs skip anything already done. This is also why uninstalling keeps that record by default.

= What happens if I uninstall the plugin? =

By default, uninstalling is non-destructive. Your backups are kept, and so is the record of which images have already been compressed. If that record were deleted, reinstalling and running a bulk compression would send your already-compressed images to the API again, using up your quota and, in lossy mode, compressing them a second time, which lowers quality.

If you genuinely want everything removed, tick **Delete all plugin data when I uninstall** in Settings before removing the plugin. Your API token is always kept, since it is yours.

= Does it work with a CDN or caching plugin? =

Yes. The plugin replaces the image files on disk, so your CDN or cache picks up the smaller versions the next time it fetches them. You may want to purge your cache after a large bulk run.

= An image failed to compress. How do I find out why? =

Open the **Needs attention** screen. Every image that failed is listed there with a plain-English reason, and stays listed until it compresses successfully. The **Logs** screen shows the most recent attempts, including skips, with the reason for each.

If you need more detail than that, you can log every call made to the API. Add this to your theme's functions.php or a small must-use plugin:

`add_filter( 'icai_debug_requests', '__return_true' );`
`add_filter( 'icai_debug_responses', '__return_true' );`

WordPress also needs debug logging switched on, in wp-config.php:

`define( 'WP_DEBUG', true );`
`define( 'WP_DEBUG_LOG', true );`
`define( 'WP_DEBUG_DISPLAY', false );`

The log is written to wp-content/debug.log.

* The requests filter records the outgoing call: HTTP method, full URL, headers and JSON body. Your API token is truncated, so the log is safe to share with support.
* The responses filter records what came back: HTTP status and the response body.

Remove both filters once you have what you need. They write a couple of lines per image, which grows the log file quickly during a bulk run.

= Uploads hang on "Crunching", or images have no thumbnails =

This happens before this plugin is involved: WordPress creates thumbnails itself during upload, and if that fails the plugin never sees the image. The usual causes are an outdated Imagick extension (versions below 3.5 crash on some files) or PHP running out of memory on a very large image.

Check your Imagick version and your memory limit under **Tools > Site Health > Info**. Raising the limit in wp-config.php often fixes it:

`define( 'WP_MEMORY_LIMIT', '512M' );`

If images in your library already have missing thumbnails from a previous failure, you can have a bulk run rebuild them:

`add_filter( 'icai_dev_regenerate_thumbnails', '__return_true' );`

Be aware this does image processing on your own server, which is exactly what this plugin normally avoids. It is slow and memory hungry, and on the very images that failed before it may fail again. Try it on a staging copy first, and remove the filter once the repair is done.

== Screenshots ==

1. Dashboard with total savings, library coverage and live quota.
2. Bulk compression with live progress, pause and resume.
3. Before and after comparison with a per-size breakdown.
4. Backups with restore and compare.
5. Activity log showing recent compressions, skips and failures.
6. Settings.

== Changelog ==

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
