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

Replace hundreds of PDFs and documents at once: match new files to posts, review every pairing, back up, replace, and roll back if needed.

== Description ==

If your site hosts a lot of downloadable documents, updating them one at a time is slow and easy to get wrong: find the right page, download the old file, upload the new one, repoint the link, repeat. Do that for a few hundred price lists, handbooks, syllabi, product manuals or forms and it becomes a job nobody wants.

WPBR Bulk Replace turns it into one batch. Upload the new files, let the plugin match each one to the post that already holds the old file, check the pairings yourself, then replace the live files in bulk. Every original is backed up first, and anything replaced can be rolled back. Use it to replace documents in WordPress without editing each page: a bulk replacement of PDFs, Word files and other downloadable resources, with the new version live at the same address (by default) so links to it keep working.

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

**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.

**Who is WPBR Bulk Replace for?**

* **WordPress agencies** who update the same kinds of documents on client sites again and again. The Free workflow runs on every site you install it on. Pro remembers the corrections and abbreviations you teach it on each site, so recurring batches need less review.
* **Universities and schools** with course materials, syllabi, handbooks and administrative documents spread across many pages.
* **Businesses** that publish price lists, catalogs, specification sheets and downloadable PDFs and need the new edition live under the same address.
* **Government and nonprofit sites** that keep policies, forms and public resources current, and want a backup and an undo for every change.
* **WooCommerce stores** with product manuals and other downloadable files. Replacing product images, gallery images and downloadable files on products needs WP Bulk Replace Pro.
* **Multisite administrators** who need the same document updated on many sites of a network. That needs WP Bulk Replace Pro and its Multisite add-on; the plugin in this directory works on one site at a time.

Everything in this section marked as Pro is a separate, optional product. Everything else on this page is free and works without it.

**Optional Pro and add-ons**

WP Bulk Replace Pro is an optional paid add-on, sold separately at [wpbulkreplace.com](https://wpbulkreplace.com/pro/). It remembers your matching corrections, abbreviations and ignore rules between batches, and can replace files stored in ACF file and image fields and WooCommerce products. Separate add-ons for Pro cover Multisite and Cloud Storage, and an AI Assistant. See the FAQ below for what each does, or [compare Free and Pro](https://wpbulkreplace.com/features/).

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.

== 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.

= Can I replace hundreds of PDFs or documents at once? =

Yes, that is what it is for. Put the new files in a batch, match them to posts, review the pairings, then replace in bulk. The workflow is upload, match, review, then back up and replace.

Practical limits, so you can plan: PDF, DOC and DOCX files are accepted by default, and the contents are checked, not only the extension. Browser uploads go one file at a time with a progress bar; for a very large set, copy the files into the staging folder over FTP and scan instead. Replacing runs in small chunks (5 files per request by default, adjustable in Settings), so the browser tab has to stay open while it runs; if it closes, finished rows stay finished and you can run the rest. The plugin does not cap the number of files, but your server's disk, memory and time limits still apply. Matching only proposes: filenames that are too different from the post's title need a manual correction on the Review screen.

= Does WPBR support WordPress Multisite? =

The plugin in the directory works on one site at a time: each site has its own batches, backups and settings. To replace files across the sites of a network in one reviewed job, with a backup on each site, you need WP Bulk Replace Pro and its optional Multisite add-on, which is sold separately. Each covered site needs Pro. Details: https://wpbulkreplace.com/add-ons/multisite/

= Can it replace files in ACF custom fields? =

Plain custom fields that hold a file URL work in this edition. Replacing files held in Advanced Custom Fields file and image fields, including fields inside a repeater or flexible content layout (one repeating level), needs WP Bulk Replace Pro. It repoints a file that is already there; it does not create ACF fields, rows or layouts. More: https://wpbulkreplace.com/pro/

= Does it work with WooCommerce downloadable products? =

With WP Bulk Replace Pro and WooCommerce active, you can replace a product's featured image, a gallery image or a downloadable file, on products and variations. It repoints a file that is already there; it is not a WooCommerce editor and does not add downloads, change prices or touch orders. Without Pro, product fields that hold a file URL as ordinary custom fields still work. More: https://wpbulkreplace.com/pro/

= What if my files are not in the standard Media Library? =

This edition finds the existing file through a post type and one or more custom fields that you choose per batch, so files referenced from a custom field work even when they are not standard attachments. It does not search post content, so a file linked only inside page text or a page builder layout is not found. Files kept in an S3-compatible cloud bucket can be replaced with the optional Cloud Storage add-on for Pro, which also keeps verified offsite backups in a bucket you own: https://wpbulkreplace.com/add-ons/cloud-storage/ Without an add-on, a file the plugin cannot back up and verify is never overwritten.

= Can AI do the replacements for me? =

There is an optional AI Assistant add-on, sold separately and requiring Pro; the Pro page at https://wpbulkreplace.com/pro/ lists the add-ons that are on sale. You describe the job in plain English and attach the new files; it sets up the batch, uploads and matches the files and prepares the replacement, with a backup first and a report afterwards. It works inside the normal WPBR screens, so you can follow every step. It works in the places an administrator has approved, has its own usage limits, and is not part of the plugin in this directory, which never contacts an AI service.

= Can I review or correct AI matches? =

Yes. The Assistant's matches appear in the same Review & Resolve screen, where you can change any of them, and an approval mode can make it show exactly which files would change and wait for you before it replaces anything. It cannot approve a plan for you.

= Do I need an API key for the AI Assistant? =

Yes. The Assistant uses your own key from a supported AI provider, which bills you directly. The add-on and Pro are required in addition; this free plugin needs neither.

= What happens if a replacement is wrong? =

Every file is copied to a backup before it is overwritten, so a wrong replacement can be rolled back from the batch screen, per row or in bulk, for as long as the backup exists. Nothing is replaced until you tick rows and run Back up and Replace, and starting with one or two files to check the live result is a normal way to work.

= What is the difference between Free and Pro? =

Free, this plugin, is a complete workflow: upload, matching, review, backups, replacement, rollback and conflict checks, with no limit on how many files you process. WP Bulk Replace Pro adds matching that remembers your corrections, abbreviations and ignore rules between batches, replacing files in ACF fields and WooCommerce products, and support tickets from your account. Compare them at https://wpbulkreplace.com/features/ and see pricing at https://wpbulkreplace.com/pricing/

= Can agencies use WPBR across multiple client sites? =

Yes. The Free plugin can be installed on as many sites as you like. Pro is an annual licence for 1, 5 or 50 sites with the same features at each size, and add-ons are licensed by site count the same way; see https://wpbulkreplace.com/pricing/ for current prices. Saved rules stay with each site rather than being shared between clients. Replacing across a network is the Multisite add-on described above.

= 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. Every file set you are updating, with its progress: what is untouched, what needs review and what is finished.
2. Review & Resolve. Each new file scored against the post it matched, filtered by confidence or status, with an editable new filename and a CSV round-trip for a second reviewer.
3. Backup & Replace. Per-row results for a batch of replaced documents, with a backup kept for every one and buttons to roll back.
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.3.0 =
* Settings are now organised into tabs, with every option you already had kept where it was saved: your settings carry over unchanged.
* The Match step runs on the same matching routine the optional add-ons use (engine services contract 2), so a batch matched for you by an add-on gets exactly the result the Match step would give. Nothing changes in how you match on screen, and rows you set by hand stay protected.
* The Batches list, the batch page and History show "Assistant" or "Connected app" when an optional add-on made a change on someone's behalf. This needs one new column on two tables (database version 3.1); it is added by itself on the first admin page load, and a site that cannot add it simply records no actor and works as before.
* Includes everything in 1.2.0 and 1.1.0.

= 1.2.0 =
* Internal release: nothing changes on screen. Batch creation, file staging, hand matches and the checks made before a write became plain functions that the optional add-ons call (engine services, contract 1).
* Detects the other edition of WP Bulk Replace before loading any code, and refuses to activate beside it with one clear message.

= 1.1.0 =
* Backups can be kept in a private folder outside the web root: a new Backups location panel checks each candidate folder before it is used, and a folder that is readable from the web is never chosen.
* Hosts that keep uploads on cloud or managed storage (for example WordPress VIP) are handled through a storage-adapter contract. WP Bulk Replace never overwrites a file it cannot back up and verify, and it refuses a file no adapter owns.
* Extension API 2: the engine records its intent before a write and concludes from it after an interrupted request. Optional add-ons plug into this contract; none is needed to use WP Bulk Replace.
* Deleting a site or the plugin keeps backups that are the only copy of an original.
* Everything in 1.0.1 is included.

= 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.3.0 =
Adds tabbed Settings, a shared matching routine for the optional add-ons, and a small database update (3.1) that runs by itself. Your batches, backups and settings carry over.

= 1.2.0 =
Adds the engine services used by optional add-ons and an activation check against the other edition. Your batches, backups and settings carry over.

= 1.1.0 =
Adds private backup folders and the storage-adapter contract used by optional add-ons. Your batches, backups and settings carry over.

= 1.0.1 =
First release on WordPress.org.
