=== AttiaWebP - Safe WebP Replace & Optimizer ===
Contributors: ahmedattia15
Tags: webp, avif, images, optimization, performance
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Local WebP/AVIF sidecar conversion, savings statistics, media library tools, background processing, WP-CLI, and optional server-level delivery.

== Description ==

AttiaWebP helps site owners convert JPEG and PNG media library images into WebP (and optionally AVIF) using the image tools available on their own WordPress server.

The default mode is conservative: it creates WebP copies next to the original files and keeps the original JPEG/PNG files untouched. Optional server-level delivery can serve matching WebP/AVIF sidecar files without rewriting front-end HTML, WooCommerce product markup, widgets, or content.

Advanced replacement tools are included for site owners who want a one-image WebP media library. These tools are disabled by default and require explicit confirmation before deleting original JPEG/PNG files or generated image sizes.

Main features:

* Automatically create WebP files after new JPEG/PNG uploads.
* Optional AVIF sidecar generation alongside WebP when the server supports AVIF encoding.
* Bulk convert existing media library images in safe, time-budgeted batches with a live progress bar and a Stop button.
* Background conversion mode that keeps working on the server through WP-Cron after the browser tab is closed.
* Media Library integration: a WebP status column, per-image savings, a one-click Convert/Regenerate button, and a bulk action.
* Estimated bandwidth savings on the dashboard, calculated from real sidecar files on disk.
* Exclusion patterns to skip specific folders or file names during conversion.
* Cursor-based bulk processing designed for large media libraries.
* Upload-file statistics for JPEG/PNG, WebP, WebP sidecar conversions, and AVIF files.
* Optional server-level WebP/AVIF delivery through a managed uploads `.htaccess` rules block on Apache/LiteSpeed servers, plus a copy-paste Nginx example.
* WP-CLI commands for status, conversion, replacement, and marker resets.
* A small on-screen log of recent conversion errors.
* Optional single image mode for future uploads.
* Optional permanent replacement mode that updates media items to WebP and deletes old JPEG/PNG files after explicit confirmation.
* Quality control for WebP (default 82) and AVIF (default 60).
* Option to skip generated files when they are larger than the source file.
* No external API calls and no third-party tracking.

Important: Always create a full backup before using permanent replacement tools. Replacement mode deletes original JPEG/PNG files and generated image sizes after successful WebP conversion.

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/` or install the ZIP through Plugins > Add New > Upload Plugin.
2. Activate the plugin through the Plugins screen in WordPress.
3. Open Settings > AttiaWebP WebP Optimizer.
4. Review the settings and save your preferred configuration.
5. Use the safe bulk conversion tool, the background mode, or the Media Library column to create WebP copies for existing media.

== Frequently Asked Questions ==

= Does this plugin delete my original images by default? =

No. By default, the plugin creates WebP copies and leaves JPEG/PNG originals untouched.

= Can it replace originals with WebP? =

Yes, but only through advanced options. Permanent replacement is disabled by default and requires a confirmation checkbox plus the exact text DELETE ORIGINALS before bulk replacement can run.

= What is AVIF and should I enable it? =

AVIF is a newer image format that is usually smaller than WebP at similar visual quality. If the settings screen shows AVIF support, you can enable AVIF sidecars so the server can deliver AVIF to browsers that accept it, WebP to older browsers, and the original file to everything else. AVIF encoding is slower than WebP, so background mode is recommended for large libraries.

= Why is the AVIF option disabled? =

Your server cannot encode AVIF. AVIF generally requires WordPress 6.5+ together with GD on PHP 8.1+ or an Imagick build with AVIF support. Ask your host about enabling it.

= What does quality 82 mean? =

It is the WebP compression quality value. Lower values create smaller files with more visible compression. Higher values preserve more detail but create larger files. The default value of 82 is a balanced starting point. AVIF uses its own quality setting with a default of 60, which is roughly comparable visually.

= Does it use an external service? =

No. Conversion uses the image editor available on the WordPress server, such as GD or Imagick.

= Will this work on every host? =

The server must support WebP through GD or Imagick. The settings screen shows a basic support check for both WebP and AVIF.

= What is background conversion? =

Background mode schedules small conversion batches through WP-Cron, so conversion continues on the server even after you close the settings page. The settings screen shows live progress and a stop button. Note that WP-Cron depends on site traffic unless a real cron job is configured.

= Does server delivery work on Nginx? =

The built-in toggle manages an uploads `.htaccess` block, which is for Apache/LiteSpeed environments. For Nginx, the settings screen now includes an example server-block snippet you can copy into your Nginx configuration manually.

= Does server delivery change my WooCommerce product HTML? =

No. Server delivery does not rewrite product HTML, image src attributes, srcset values, content, widgets, or custom CSS. It only lets the server return a matching WebP/AVIF file for JPEG/PNG requests when the browser supports the format and a matching sidecar file exists.

= How do I exclude certain images? =

Add patterns to the Exclusions box, one per line, matched against the path relative to the uploads folder. `*` works as a wildcard, for example `2024/private/*` or `*-logo.png`.

= Should I use permanent replacement on a live store? =

Only after testing on staging and creating backups. Some themes, builders, or stores may rely on generated image sizes.

== Developers ==

WP-CLI commands:

* `wp attiawebp status` - Shows support details, pending counts, and background state.
* `wp attiawebp convert [--limit=<n>] [--force]` - Creates WebP/AVIF sidecars for pending attachments.
* `wp attiawebp replace --confirm=DELETE-ORIGINALS [--limit=<n>]` - Runs the permanent replacement flow.
* `wp attiawebp reset-markers [--which=sidecar|replace]` - Clears conversion or skip markers.

Filters:

* `aawo_conversion_quality( int $quality, string $mime, string $file )` - Adjusts quality per file or format.
* `aawo_should_convert_file( bool $convert, string $file, int $attachment_id )` - Skips or allows specific files.
* `aawo_delivery_rules( string $rules, bool $avif_enabled )` - Modifies the managed `.htaccess` rules block.
* `aawo_batch_time_budget( int $seconds )` - Changes the per-batch time budget for bulk processing.

== Privacy ==

AttiaWebP does not send images, site data, or usage data to external services. All conversion work happens locally on the WordPress server.

== Changelog ==

= 1.2.0 =
* Added optional AVIF sidecar generation with its own quality setting and server support detection.
* Added a Media Library WebP column with status badges, per-image savings, a one-click Convert/Regenerate button, and a bulk action.
* Added background conversion through WP-Cron with live progress, so large libraries convert without keeping the tab open.
* Added a progress bar, a Stop button, and per-batch counters to the interactive bulk tools.
* Added an estimated bandwidth savings card based on real sidecar files on disk.
* Added exclusion patterns to skip folders or file names during conversion.
* Added WP-CLI commands: status, convert, replace, and reset-markers.
* Added AVIF-aware server-delivery rules and a copy-paste Nginx configuration example for non-Apache servers.
* Added a capped on-screen log of recent conversion errors with a clear action.
* Added reset tools for conversion markers and previously skipped replacements.
* Batches now respect the PHP time limit and stop early instead of timing out on slow hosts.
* Added developer filters for quality, file exclusion, delivery rules, and batch time budget.
* Added an RTL admin stylesheet.

= 1.1.1 =
* Hardened server-delivery rule management and avoided creating an empty uploads `.htaccess` file when delivery is disabled.
* Added admin notices when server-delivery rules cannot be written.
* Reworked bulk processing to use cursor-based batches instead of loading every attachment ID into memory.
* Added cached upload-file statistics with a manual refresh link.
* Disabled bulk buttons when WebP support is not available on the server.
* Refreshed the translation template and WordPress.org package metadata.

= 1.1.0 =
* Added optional server-level WebP delivery using managed uploads `.htaccess` rules.
* Kept front-end HTML rewriting disabled to avoid theme, WooCommerce, WPML, and cache-plugin conflicts.

= 1.0.1 =
* Safe store build: disabled front-end URL rewriting and added real upload-file statistics.

= 1.0.0 =
* Initial public release.

== Upgrade Notice ==

= 1.2.0 =
Major update: AVIF sidecars, Media Library tools, background conversion, savings statistics, WP-CLI commands, Nginx delivery example, and exclusion patterns. Settings are preserved; review the new options after updating.
