=== Auto-Rename Images on Upload ===
Contributors: snehalpancholi
Tags: image rename, seo filenames, upload rename, media library, image optimization
Requires at least: 6.0
Tested up to: 6.7
Requires PHP: 8.1
Stable tag: 1.0.0
License: GPL-2.0+
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Automatically rename uploaded image files to clean, SEO-friendly slugs before WordPress saves them — using filename cleanup, post title, or a custom token pattern.

== Description ==

**Auto-Rename Images on Upload** intercepts every image upload and renames the file to a clean, SEO-friendly slug before WordPress records it in the database. No database patching, no redirect rules needed — the file arrives with the right name from the start.

= Three Rename Modes =

* **Clean Original Filename** — strips special characters, applies your separator, lowercases and truncates the existing filename slug.
* **Parent Post Title** — derives the filename from the post or page the image is being attached to (falls back to clean filename when uploading outside a post).
* **Custom Pattern** — build your own filename template using tokens like `{filename}`, `{post_title}`, `{date}`, `{year}`, `{month}`, `{site_name}`, and more.

= Highlights =

* Runs before WordPress saves the file — zero impact on existing media library entries.
* Handles filename collisions automatically (`my-photo-2.jpg`, `my-photo-3.jpg`, …).
* Configurable separator (hyphen or underscore), forced lowercase, max-length truncation, and optional stripping of leading/trailing numbers.
* Applies only to the MIME types you choose: JPEG, PNG, GIF, WebP.
* Optional rename log stored as attachment meta — browse the last 20 renames on the settings page and clear with one click.
* Live preview tool: paste a sample filename and see exactly what it would become under current settings.
* No jQuery, no external dependencies, no bloat.

= Pattern Tokens =

| Token | Output |
|---|---|
| `{filename}` | Cleaned original filename (no extension) |
| `{post_title}` | Parent post title, slugified |
| `{date}` | Current date in Ymd (e.g. 20260615) |
| `{time}` | Current time in His (e.g. 143022) |
| `{year}` | Four-digit year |
| `{month}` | Two-digit month (01–12) |
| `{day}` | Two-digit day (01–31) |
| `{site_name}` | Sanitized site name |

== Installation ==

1. Upload the `auto-rename-images` folder to `/wp-content/plugins/`.
2. Activate the plugin through **Plugins → Installed Plugins**.
3. Go to **Settings → Auto-Rename Images** to configure rename mode, pattern, separator, and logging options.
4. Upload a test image from the Media Library or from an edit post screen to verify the renaming.

== Frequently Asked Questions ==

= Does it rename existing images already in the media library? =

No. The plugin only renames new uploads at the moment they arrive. Existing attachments and their URLs are never touched.

= Will renaming break existing URLs or embedded images? =

No. Because the rename happens before WordPress records the attachment, the URL stored in the database is already the clean one. There is nothing to update, and no redirect rules are needed.

= What happens if two uploads would produce the same filename? =

The plugin automatically appends a numeric suffix: `product-photo.jpg` → `product-photo-2.jpg` → `product-photo-3.jpg`, and so on. It checks for physical file existence in the upload directory to guarantee uniqueness.

= What if I upload from the Block Editor versus the classic Media Library popup? =

Both paths go through the same WordPress upload handler (`wp_handle_upload`). The rename hook fires for both. When uploading from the Block Editor on a post edit screen, `$_POST['post_id']` is typically set, so post-title mode works correctly.

= Does the plugin rename non-image file types? =

Only the MIME types you enable in settings (JPEG, PNG, GIF, WebP by default). Other file types (PDFs, videos, documents) are passed through unchanged.

= Can I use a pattern without the date? =

Yes. Just set your pattern to only the tokens you want, e.g. `{post_title}-{filename}`.

= Where is the rename log stored? =

Rename data is saved as attachment post meta (`_addlc_ari_original_name`, `_addlc_ari_new_name`, `_addlc_ari_rename_date`). This data is private (prefixed with `_`) and not visible to other plugins unless they specifically query for it.

= Is the plugin multisite compatible? =

Yes. Options and meta are stored per-site. Each subsite maintains its own settings.

== Screenshots ==

1. **Settings page** — Configure rename mode, separator, pattern, file types, and logging in one clean screen.
2. **Pattern mode** — Custom token pattern with clickable token chips for easy insertion.
3. **Preview tool** — Test any sample filename against current settings before going live.
4. **Recent renames log** — See the last 20 renamed attachments with original and new filename.

== Changelog ==

= 1.0.0 =
* Initial release.
* Three rename modes: clean filename, post title, custom pattern.
* Eight pattern tokens.
* Automatic collision handling.
* Live preview AJAX tool.
* Rename history log with clear button.
* Configurable separator, lowercase, strip-numbers, max-length, and MIME type filters.

== Upgrade Notice ==

= 1.0.0 =
Initial release. No upgrade steps required.
