=== Media Rename — OrbitStem ===
Contributors: pratik2198, concatstring
Tags: rename, media, seo, images, redirect
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.9.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Rename media files safely: updates every link, adds 301 redirects, keeps a full undo history, and finds badly named files for you.

== Description ==

**Media Rename — OrbitStem** renames images, PDFs and any other media files without breaking your site. Every feature is free — no Pro version, no ads.

Before you rename, you see where the file is used, every file that will change (all thumbnail sizes, the original of large photos, WebP/AVIF copies) and, if you want, the exact database rows that will be updated. After the rename, links are updated across posts, custom fields, page builders and settings, the old URLs redirect with a 301, and you can undo at any time.

**Rename**

* **Rename panel** in the Media Library and on the attachment edit screen, with quick suggestions from the title, alt text or post, an SEO score, and a usage report
* **Every file renamed together** — main file, all sizes, the pre-scaled original of large photos (`-scaled`), and WebP/AVIF copies made by optimisation plugins
* **Move to another folder** inside uploads, with links and redirects updated
* **Lock files** so bulk and automatic renames never touch them
* **Show exact changes** — a dry run that lists every database row a rename will update

**Bulk and automatic**

* **Filename audit** — finds camera names (`IMG_1234`, `DSC_`, `PXL_`), screenshots, random hashes, numbers-only and non-Latin names, suggests better names, and fixes them in bulk
* **Bulk rename** with templates: `{post-title}`, `{attachment-title}`, `{counter:3}`, `{sku}`, `{product}`, `{category}`, `{date}`, `{uuid}` and more — the preview shows exactly the names that will be used
* **Rename a post's images** from the post, page or WooCommerce product editor (featured image, content images, gallery and variation images)
* **Rename when the title changes** (optional)
* **Auto-rename on upload** — transliterate non-Latin names (Москва → moskva, 東京 → dong-jing), lowercase, hyphens, strip camera codes, dates, hashes and stopwords, add a prefix; also for URL imports and importers. Off until you turn it on
* **Metadata sync** — set the title, alt text and caption from the file name, only when they are empty or generic, or always
* **Background jobs** — bulk renames run in small steps, continue with WP-Cron if you close the page, and resume safely after a timeout. On large sites a single rename also updates links in the background, with a progress bar

**Safety**

* **Automatic 301 redirects** for every renamed file and size, stored in their own table, with hit counts
* **History** of every rename, with undo for a single file or a whole bulk job, and CSV export
* **Repair tool** finds links to old file names left behind (for example content added later) and fixes them
* **Page builders and caches** — Elementor, Divi, Bricks, Breakdance, Beaver Builder, Gutenberg; WP Rocket, LiteSpeed, W3TC, WP Super Cache, Cloudflare, SiteGround, Nginx Helper and more
* **WP Offload Media** — offloaded files are detected and protected from renames that would break them

**For developers**

* WP-CLI: `wp orbitstem rename`, `bulk`, `audit`, `undo`, `repair` (with `--dry-run`)
* REST API: `orbitstem/v1/media/{id}/rename`, `/preview`, `/undo`, `/lock`
* Actions: `orbitstem_after_rename`, `orbitstem_after_rollback`, `orbitstem_after_content_sync`, `orbitstem_purge_urls`
* Filters: `orbitstem_rename_capability`, `orbitstem_allow_editors_to_rename`, `orbitstem_rename_blocked_reason`, `orbitstem_content_sync_pairs`, `orbitstem_url_hosts`, `orbitstem_extra_tables`, `orbitstem_single_sync_budget`, `orbitstem_show_post_images_box`

**WordPress Playground**

Try it in your browser: `https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/pratik2198/orbitstem-media-rename/trunk/blueprint.json`

**Privacy**

This plugin does not contact external servers, track users, or collect personal data.

== Installation ==

1. Upload the `orbitstem-media-rename` folder to `/wp-content/plugins/`
2. Activate the plugin through the **Plugins** menu
3. Open **Media → Library**, click a file, and use the **Media Rename** panel
4. Go to **Media → Media Rename** for the filename audit, bulk rename, rules, history and settings

== Frequently Asked Questions ==

= What can I type as the new name? =

Anything. Accents, spaces, dots and symbols are cleaned up for you, and the rename panel shows the result as you type: `Café Paris 2.0` is saved as `Cafe-Paris-2-0`. If you type an extension such as `.jpg` it is ignored; the file keeps its own.

= Is auto-rename on after installing? =

No. New installs don't change any uploads until you choose. A one-time notice offers the recommended rules (lowercase, hyphens, transliteration), or pick your own under **Media Rename → Auto-Rename Rules**. Sites updating from an earlier version keep the rules they had.

= Who can rename media files? =

Administrators by default. Under **Media → Media Rename → Settings** you can allow editors, or authors (for files they can edit). Developers can also use the `orbitstem_rename_capability` filter.

= Will renaming break links or search rankings? =

No. Links on your site are updated, and every old file URL (including all thumbnail sizes) gets a 301 redirect to the new file, so external links and image search keep working.

= What happens if a rename is interrupted? =

The undo record and redirects are saved before links are updated. On large sites the rename finishes right away and the link update continues in the background with a progress bar (it keeps going with WP-Cron if you close the page). If anything stops part-way, the History tab marks the rename as interrupted and **Guide & Tools → Repair old links** finishes it. Bulk jobs resume automatically.

= Can I undo? =

Yes. **Undo last rename** in the panel, **Roll back** in Rename History (the most recent rename of each file), or **Undo this whole job** for a bulk run.

= Does it work with WooCommerce? =

Yes. Product images, gallery and variation images are renamed with links updated, the `{sku}` and `{product}` tokens are available, and the product editor has a box to rename all of a product's images.

= Are non-English file names supported? =

Yes. With the transliteration rule (**Auto-Rename Rules**), Cyrillic, Greek, Chinese, Arabic and accented letters become readable Latin letters instead of being removed. For example `Дача.jpg` becomes `dacha.jpg`. Chinese, Japanese and Korean need the PHP intl extension, which most hosts have.

= Can I see exactly what will change before renaming? =

Yes. The rename panel lists every file that will be renamed, and **Show exact database changes** lists every post, custom field and setting that will be updated. Bulk rename has a dry-run preview that shows the final names, and WP-CLI commands accept `--dry-run`.

= How does the filename audit work? =

**Media → Media Rename → Filename Audit** scans your library for camera names (`IMG_1234`, `DSC_`, `PXL_`), screenshots, random hashes, numbers-only, non-Latin and very short or long names. Each file gets a suggested name from its alt text, title or post, which you can edit. Tick the files and click **Rename selected**.

= Can the title and alt text follow the file name? =

Yes. Under **Metadata Sync** choose, for title, alt text and caption, "Never change", "Only when empty or generic" (fills blanks and replaces names like IMG_1234 without touching text you wrote) or "Always".

You can also fill alt text on upload: each image gets the post title plus its own file name ("Our Summer Menu – Pasta"), so images in the same post don't share one alt text. And files with a generic name (IMG_1234, a hash, a screenshot name) can be renamed automatically when you give them a title; files that already have a real name are never renamed by a title edit.

= Does it change links to other websites? =

No. Only links to your own site are updated: http, https, with or without www, in any letter case, root-relative links (in HTML, CSS, JSON or plain text) and Jetpack image CDN links (i0.wp.com/yoursite.com/…). If your images are served from a CDN, add its domain under **Settings → CDN domains**. A link such as `https://partner-site.com/wp-content/uploads/logo.jpg` is never changed, even if your own logo has the same name.

= How does the repair tool work? =

**Guide & Tools → Repair old links** finds links that still use old file names, for example content added after a rename, renames done with "Update URLs everywhere" turned off, or an interrupted rename. Click **Scan for old links** first to see every change, then **Repair these links**. Links to a file name that another file now uses are left alone. Only administrators can run it.

= How do I stop a file from being renamed? =

Click **Lock file** in its rename panel. Locked files are skipped by bulk rename, audit fixes and automatic renames. Under **Settings** you can lock files automatically after you rename them by hand.

= Can I move files to another folder? =

Yes. Open **Move to another folder** in the rename panel and enter a folder inside uploads, for example `products/shoes`. All sizes move together, links are updated and the old URLs redirect.

= Can I use it from the command line? =

Yes, with WP-CLI:

    wp orbitstem rename 123 red-running-shoes --dry-run
    wp orbitstem bulk --ids=10,11,12 --template="{post-title}-{counter}"
    wp orbitstem audit --issue=camera --format=csv
    wp orbitstem undo 123
    wp orbitstem repair --dry-run

Run `wp help orbitstem` for all options.

= Does it work with PDFs and other files? =

Yes. Any file in the Media Library can be renamed. Image-only features (sizes, alt text, WebP copies) are simply skipped for other file types.

= Does it work with WP Offload Media or other cloud storage? =

Files that WP Offload Media has copied to cloud storage are detected and cannot be renamed, because renaming only the local copy would break the cloud link. Other files work as usual.

= Will it slow down my site? =

No. Nothing runs on normal page views. Redirects are only checked when a missing file in the uploads folder is requested. Renames and bulk jobs run in the admin, in small steps.

= What happens to my data if I delete the plugin? =

Renamed files keep their new names and links stay updated. Deleting the plugin removes its settings and rename history. The redirect list is kept by default (**Settings → Keep redirects when deleted**), so reinstalling restores it.

Redirects only run while the plugin is active. To keep old image links working without the plugin, download them from the **301 Redirects** tab as Apache (.htaccess) or nginx rules and add them to your server. Deactivating (without deleting) keeps everything.

= How do I check that redirects work? =

Click **Test redirects** in the **301 Redirects** tab. It requests the newest old links and tells you if each one reaches the new file. Some servers answer missing images themselves before WordPress runs; the test then says so, and you can add the exported Apache or nginx rules.

= Does it update SEO plugin data? =

Yes. Yoast SEO and Rank Math social images stored in post meta are updated, and so is Yoast's own indexables table. Developers can add other plugin tables with the `orbitstem_extra_tables` filter.

== Screenshots ==

1. **Media Rename panel** in attachment details: files that will change, SEO score, usage report and one-click rename.
2. **Bulk rename** with pattern templates such as `{post-title}-{counter}`.
3. **Dry-run preview** of current and new names, with conflict warnings, before anything changes.
4. **Progress bar** for bulk jobs, which continue in the background.
5. **Rename history** with rollback.
6. **Automatic 301 redirects** for old file URLs.
7. **Auto-rename rules** on upload with a live preview.
8. **Rename panel**: every file that will change, usage report, and the exact database rows that will be updated.
9. **Filename audit**: camera names, hashes and screenshots found, with suggested names ready to fix in bulk.
10. **Bulk rename** with all tokens and a dry-run preview of the final names.
11. **Rename a product's images** from the WooCommerce product editor.
12. **Metadata sync**: title, alt text and caption follow the file name; rename when the title changes.
13. **Rename history** for one bulk job, with "Undo this whole job".
14. **Settings**: who can rename, lock after manual rename, and CDN cache purging.

== Changelog ==

= 1.9.2 =
* **Fixed:** Since 1.9.1 some links to your own files were no longer updated: domain in capitals, CSS `url(&quot;…&quot;)`, a path as link text or on its own line, and Jetpack image CDN links. They are updated again, and links to other websites are still left alone.
* **Fixed:** Typing a name with accents, spaces or dots (`café-paris`, `Big Sale`, `version-2.0`) gave an error. The name is now cleaned up and the panel shows what will be saved.
* **Fixed:** Bulk rename named unattached images post-1, post-2. The default pattern is now `{attachment-title}-{counter}`, which uses the media title, then the post title, then a cleaned file name; `{post-title}` also falls back to the media's own name.
* **Changed:** Auto-rename is off on new installs, with a one-time "Turn on auto-rename?" notice. Existing sites keep their rules.
* **Improved:** On large sites a single rename no longer risks a timeout: links are updated in steps in the background, with a progress bar.
* **New:** **Test redirects** button checks that old links really reach the new files.

= 1.9.1 =
* **Fixed:** The repair tool could point a post at the wrong image when a file name had been reused by another file. Names in use again, and files that no longer exist, are now skipped.
* **Fixed:** The repair tool didn't fix links left by renames done with "Update URLs everywhere" turned off. It now does, and follows files renamed more than once (A → B → C).
* **New:** The repair tool shows every change first ("Scan for old links"), and `wp orbitstem repair --dry-run`.
* **Fixed:** Links to other websites with the same file path could be changed. Only links to your own domains (and CDN domains you list in Settings) are updated now.
* **Fixed:** Editors and authors allowed to rename could run the site-wide repair tool. It is now administrators only.
* **Fixed:** "Fill alt text on upload" gave every image in a post the same alt text. It now combines the post title with each file's name.
* **Fixed:** "Rename when the title changes" renamed files on every title edit. It now only renames files with generic names (IMG_1234, hashes, screenshots) and not twice within 10 minutes.
* **Fixed:** The history CSV export showed every user's renames to non-administrators; they now get only their own.
* **Improved:** Deleting the plugin keeps the redirect list by default; redirects can be exported as Apache, nginx or CSV.
* **Improved:** Yoast SEO's indexables table is updated on rename; other plugin tables can be added with the `orbitstem_extra_tables` filter.

= 1.9.0 =
* **New:** Filename audit — find and fix camera names, screenshots, hashes, numbers-only and non-Latin names in bulk.
* **New:** Metadata sync — set title, alt text and caption from the file name; optional rename when the title changes; optional alt text on upload.
* **New:** Transliteration of non-Latin file names on upload, in suggestions and in tokens (previously these letters were removed).
* **New:** Lock files; move files to another folder; "show exact database changes" dry run.
* **New:** Rename all images of a post or WooCommerce product from its editor; `{sku}`, `{product}`, `{attachment-title}`, `{date}`, `{id}`, `{site}`, `{random}` and `{uuid}` tokens.
* **New:** Undo a whole bulk job; repair tool for leftover old links; CSV export of history and bulk plans.
* **New:** WP-CLI commands and REST API endpoints.
* **New:** "Who can rename" setting; CDN cache purging; WebP/AVIF copies named `photo.jpg.webp` and Performance Lab copies are renamed too.
* **Fixed:** Renaming with "Update URLs everywhere" could wipe widgets, theme settings and custom fields (double serialization).
* **Fixed:** Renaming to a taken name pointed posts at the other image.
* **Fixed:** Photos larger than 2560px (`-scaled`) were only half renamed.
* **Fixed:** A second rename erased the history and old redirects.
* **Fixed:** Backslashes were removed from posts; custom Yoast / Rank Math social images were deleted.
* **Fixed:** Rollback from the History page failed for most entries; bulk jobs could run twice and rename files twice.
* **Fixed:** Rolling back could point posts at the wrong file; only the newest rename of a file can now be rolled back.
* **Fixed:** Sites without year/month folders got broken thumbnail links, and other images' links could be changed.
* **Fixed:** Renames by editors stripped embeds and iframes from posts; posts no longer get a revision per rename.
* **Fixed:** An interrupted rename could leave no undo record.
* **Fixed:** Redirects could send visitors to wp-admin after a domain/CDN change, missed encoded file names, and were silently dropped after ~150 renames.
* **Fixed:** Beaver Builder layouts were not updated; JSON values were re-formatted.
* **Fixed:** Bulk dry run didn't always match the result; bulk failures are now listed with a reason.
* **Fixed:** Permission checks for bulk, history and job status; escaping in the bulk preview; the review notice can now be dismissed.
* **Improved:** History and redirects moved to their own database tables (no 500-entry / 2,000-redirect limits); faster usage scan that also finds sized image URLs; uninstall removes all plugin data; translations and accessibility.
* **Removed:** The WordPress Playground button on the Guide tab (the link is still in this readme).

= 1.8.0 =
* Batched bulk rename, rename history with rollback, automatic 301 redirects, expanded auto-rename rules, conflict handling and cache purging.

= 1.7.0 =
* Auto-rename on upload with live preview.

= 1.6.0 =
* International filenames, PHP 7.4 support, Windows path fixes.

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.9.2 =
Fixes own links that 1.9.1 stopped updating (capital letters, CSS, Jetpack CDN), cleans typed names instead of rejecting them, and better bulk names. Large sites update links in the background.

= 1.9.1 =
Fixes the repair tool pointing posts at the wrong image, and links to other websites being changed on rename. Recommended for everyone on 1.9.0.

= 1.9.0 =
Important fixes: URL updates could damage widgets and theme settings, and History rollback rarely worked. Adds filename audit, metadata sync, transliteration, WP-CLI and more. History and redirects are migrated to new tables automatically.
