=== WPBR Bulk Replace ===
Contributors: bohdansmaha
Tags: bulk edit, attachments, media, pdf, custom fields
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Match a folder of files to your posts, review every pairing, then back up and replace the live files in bulk.

== Description ==

Replacing a few hundred PDFs attached to a few hundred pages is a job nobody wants: find the right page, download the old file, upload the new one, repoint the field, repeat. WPBR Bulk Replace does the matching for you and then makes you check it before anything is written.

It works against any post type and any meta field that holds a file URL, so it is not tied to a particular theme or page builder.

WPBR Bulk Replace is the WordPress.org edition of WP Bulk Replace, which is also distributed independently from wpbulkreplace.com. The two editions are built from the same source and have the same features; this one updates through WordPress.org.

**How it works**

1. **Upload** &mdash; drag files in, or drop them into the staging folder over FTP and scan.
2. **Match** &mdash; pick the post type and the meta field holding the file URL, then run matching. Each filename is scored against every published post of that type. Re-running is safe: rows you set by hand are protected.
3. **Review and resolve** &mdash; correct anything that matched wrongly, filter by confidence or status, and export a CSV if you want a second opinion from someone else.
4. **Back up and replace** &mdash; tick the rows you want and process them. Every replacement is backed up first, and anything processed can be rolled back from the same screen.

**Built to be careful**

* **Every replacement is backed up.** Rollback is one click, per row or in bulk.
* **Conflicts block processing.** If two files match the same post they would overwrite each other, so replacing stops until you resolve it.
* **Creating is separated from replacing.** If a post has no file yet, replacing becomes creating, which needs its own approval.
* **Imports are undoable.** Every reviewer CSV import can be reversed later, not just immediately.
* **Your data stays yours.** Deleting the plugin leaves your batches, history and backups intact unless you explicitly opt in to removal.

**Works with**

PDF, DOC and DOCX files. Reviewer spreadsheets can be CSV or XLSX.

== Installation ==

1. In WordPress, go to Plugins &rarr; Add New, search for "WPBR Bulk Replace", then click Install Now and Activate. With WP-CLI: `wp plugin install wpbr-bulk-replace --activate`.
2. Go to **Bulk Replace** in the admin menu and create your first batch.

You will need administrator access, and a way to get files onto the site &mdash; either the browser uploader or FTP/SFTP access to the staging folder.

== Frequently Asked Questions ==

= Will this overwrite files without asking? =

No. Nothing is written until you tick rows and click through the Back up and Replace step, and every file replaced is copied to a backup folder first.

= Can I undo a replacement? =

Yes. Processed rows can be rolled back from the batch screen for as long as their backup exists. Deleting backups is always a deliberate action, never automatic.

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

By default, nothing is removed. Your batches, history, settings and backups stay in place and are picked up again if you reinstall.

There is a setting to opt in to full removal. Turning it on and then deleting the plugin permanently destroys staged files and backups &mdash; which means processed rows can no longer be rolled back &mdash; along with the plugin's tables and settings. It never touches your Media Library, the replacement files now live on your site, or the meta values on your posts.

Externally pinned staging or backup directories are not deleted automatically during uninstall and must be removed manually if desired.

= How is WPBR Bulk Replace related to WP Bulk Replace? =

They are two editions of the same plugin by the same author. WP Bulk Replace is distributed from wpbulkreplace.com and updates from there; WPBR Bulk Replace is the WordPress.org edition and updates from WordPress.org. Features and data are the same.

Because they share their data, only one can be active at a time. If one is active, the other declines to activate and says why. Neither edition deactivates, removes or changes the other.

= I already use WP Bulk Replace. How do I switch? =

1. Deactivate WP Bulk Replace.
2. Activate WPBR Bulk Replace. Your batches, history, backups and settings are picked up as they are.
3. Optionally, delete WP Bulk Replace from the Plugins screen **while WPBR Bulk Replace is active**. WPBR Bulk Replace then keeps the shared data, even if "Delete all data when the plugin is deleted" is switched on.

Switching back works the same way: deactivate WPBR Bulk Replace, activate WP Bulk Replace, then delete WPBR Bulk Replace if you like. Deleting WPBR Bulk Replace never deletes the shared data while WP Bulk Replace is installed.

**One case is not protected.** If "Delete all data when the plugin is deleted" is switched on, and you delete WP Bulk Replace while WPBR Bulk Replace is installed but *not active*, WP Bulk Replace's uninstaller deletes the shared batches, history, backups and settings, exactly as that setting says. WPBR Bulk Replace cannot step in, because an inactive plugin runs no code. To avoid it, delete WP Bulk Replace while WPBR Bulk Replace is active, or switch that setting off first (it is off by default). The Plugins screen warns about this while WPBR Bulk Replace is active and the setting is on.

= Can I keep backups outside the web root? =

Yes, and it is the better place for them. Backups are copies of live documents, so a folder inside `uploads` relies on a deny rule that some servers ignore. Point the plugin somewhere else in `wp-config.php`:

`define('WPBR_BACKUPS_DIR', '/path/outside/webroot/wpbr-backups');`
`define('WPBR_STAGING_DIR', '/path/outside/webroot/wpbr-staging');`

Either constant overrides the matching field on the Settings screen, which then shows the folder read-only. The path must be absolute; the folder is created if it does not exist.

The folder fields on the Settings screen deliberately cannot do this &mdash; they only accept paths inside `wp-content`, because a path typed into the admin should not be able to direct writes anywhere on the server.

= I replaced a file, but my site still shows the old one. =

Usually the replacement worked and a browser, a caching plugin or a CDN is showing a copy it saved earlier. Replacing keeps the file's address on purpose, so nothing that links to it breaks &mdash; and a cache cannot tell the file changed.

Under Bulk Replace &rarr; Settings, "Add a version to links to replaced files" is on by default. It adds a small marker such as `?updated_on=20261014-093015` to the document links (PDF, Word, Excel and similar files) WordPress builds from your Media Library on your public pages, for files this plugin replaced, so browsers fetch the new file. Nothing stored is changed. It does not reach links typed into your content (including the File block), images, audio or video, or pages that a cache has saved a copy of until you clear that cache. If a download or preview feature on your site stops working for a file you replaced, turn the setting off.

= Does the plugin contact any outside service? =

No. Updates come from WordPress.org like any other plugin from the directory. The only request the plugin makes itself is to your own site, to check that its backups folder is not publicly readable. Links to the Help Center open in your browser only when you click them.

= Is there a paid version? =

Yes, optional. WP Bulk Replace Pro is a separate add-on sold at wpbulkreplace.com. It remembers corrections between batches, manages abbreviations and ignore rules, and adds ACF and WooCommerce media support. Everything described on this page is free and works without it.

= Does it work with custom post types and custom fields? =

Yes. The post type and meta field are chosen per batch. Multiple meta fields can be given as a fallback chain.

= Does it need a page builder or a particular theme? =

No. It reads and writes post meta directly.

= Can someone else review the matches? =

Yes. Export the batch as a CSV, have them mark it up, and import it back. Each import can be undone.

= Where do I get help? =

The Help Center at https://help.wpbulkreplace.com first, then this plugin's support forum on WordPress.org.

The plugin is maintained by one person rather than a team, so a reply usually takes a few working days and is not guaranteed &mdash; anything involving lost files or lost backups jumps the queue.

A report is much easier to answer if it says what you expected, what happened instead, which screen you were on, and your WordPress, PHP and plugin versions. If it is about matching or replacing, switch on Diagnostics under Settings and include that output &mdash; but read it before you post it, because it contains server paths and may contain filenames you would rather not publish.

= How do I report a security problem? =

Privately, never in the support forum: email hello@wpbulkreplace.com with "Security" in the subject line, and you will get a reply with a private channel. Please include the plugin version, what an attacker could do and what access they need first, and steps to reproduce.

== Screenshots ==

1. Batches, with progress through each one &mdash; what is untouched, what is mid-review, and what is finished.
2. Review & Resolve. Every file scored against the post it matched, filtered by confidence or by status, with the suggested new filename editable per row.
3. Backup & Replace. Per-row status, the file each one wrote, and a backup kept for every replacement until you delete it.
4. Settings. Where staging and backups live, what counts as a confident match, and exactly what is removed if you ever delete the plugin.

== Changelog ==

= 1.0.1 =
* First release on WordPress.org: the directory edition of WP Bulk Replace 1.0.1.
* New admin design across every screen.
* Backups and staged files are checked for public access with several file types (documents, images, no extension) before anything is replaced; a folder that any of them can read stops the run and says why.
* Protected backups are never deleted or moved by uninstall or by deleting a site while they are the only copy.
* A backup that cannot be confirmed is no longer called a safe original; damaged files can be retried from the batch page.
* Saving variant groups refuses text that is not a list of groups instead of replacing the saved rules with nothing.
* Deleting the plugin from the Plugins screen completes without error.

== Upgrade Notice ==

= 1.0.1 =
First release on WordPress.org.
