=== Wrenio Media Offload ===
Contributors: wrenio, freemius
Tags: cloudflare, r2, media, offload, cdn
Requires at least: 5.0
Tested up to: 6.9
Requires PHP: 8.0
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Offload WordPress media to Cloudflare R2 with URL rewriting, bulk sync, reconciliation, filename repair, and orphan cleanup.

== Description ==

Move your WordPress media library to Cloudflare R2 — and serve every attachment from R2 (or a custom domain mapped to your bucket) without changing how WordPress works elsewhere.

**What it does**

*   Uploads new media to R2 as attachments are added (via scheduled background sync).
*   Uploads existing media in batches via the Bulk Sync page.
*   Rewrites attachment, `srcset`, and in-content image URLs to the R2 (or CDN) origin.
*   Optionally deletes the local file after a successful upload to save disk inodes.
*   Fills in thumbnail metadata for attachments whose local file has been deleted.
*   Reconciles R2 object keys with local paths if they have drifted.
*   Repairs filename-level mismatches between WordPress and R2.
*   Identifies orphan R2 objects that are no longer referenced by any attachment.

**Credentials**

Credentials can be stored in the database via the settings page, or — recommended — defined as constants in `wp-config.php`:

`define( 'WRENIO_R2_ACCOUNT_ID',        'your-account-id' );`
`define( 'WRENIO_R2_ACCESS_KEY_ID',     'your-access-key' );`
`define( 'WRENIO_R2_SECRET_ACCESS_KEY', 'your-secret-key' );`
`define( 'WRENIO_R2_BUCKET_NAME',       'your-bucket-name' );`
`define( 'WRENIO_R2_PUBLIC_URL',        'https://media.example.com' );`

Constants take priority over values stored in the database.

**The reconciliation tool**

R2 object keys are derived from the stable `_wp_attached_file` meta. If keys drift away from an attachment's physical file path — for example, due to external tooling or imported content — the Reconcile page detects the drift and previews the realignment plan.

Run **Wrenio Media Offload → R2 Reconcile** → "Start Dry Run" to scan and preview a fix plan. (Live realignment that moves R2 objects to their correct keys is available in the Pro version — see below.)

**Cleanup tools**

*   **Filename Cleanup** detects attachments where the filename portion of `_wp_attached_file` differs from the R2 key (typically caused by double-dot or similar normalization mismatches) and repairs the WordPress meta to align with R2.
*   **Orphan Cleanup** walks the bucket via ListObjectsV2, builds the set of keys referenced in post meta, and offers a reviewable list of R2 objects that aren't referenced anywhere. Deletion is opt-in per batch.

**Pro version**

A Pro version is available at https://wrenio.studio/ for users who need the destructive operations: live R2 reconciliation (moving drifted objects to their correct keys), orphan deletion (removing unreferenced R2 objects), and retry counter resets.

== External Services ==

This plugin connects to the following external services. They are listed here so you know what data leaves your site and when.

**Cloudflare R2 — required for the plugin to function.**

You configure your own Cloudflare R2 credentials. The plugin uses them to upload, download, list, and delete objects in your bucket — only the bucket(s) you specify. No request is ever made to Cloudflare without your credentials, and the credentials never leave your server.

*   What is sent: the media files you upload to WordPress, plus the API requests needed to manage those files in R2.
*   When: on attachment upload, during bulk sync, and during reconciliation or orphan-cleanup runs you initiate.
*   Cloudflare terms of service: https://www.cloudflare.com/terms/
*   Cloudflare privacy policy: https://www.cloudflare.com/privacypolicy/

**Freemius — used for plugin updates and Pro licensing.**

This plugin uses the Freemius SDK to deliver plugin updates and (if you purchase a Pro license) to validate that license. By default, Freemius collects nothing from your site without your explicit opt-in. If you opt in at activation, anonymous usage statistics are shared to help improve the plugin; you can opt out at any time from the plugin's Account page.

*   What is sent: only what you opt into when you first activate the plugin (or nothing at all if you skip the opt-in). When activating a Pro license, the license key is sent to Freemius for verification.
*   When: at activation (one-time prompt), when a Pro license is activated or deactivated, and during update checks.
*   Freemius terms of service: https://freemius.com/terms/
*   Freemius privacy policy: https://freemius.com/privacy/

== Installation ==

1. In WP admin → **Plugins → Add New**, search for **Wrenio Media Offload**.
2. Click **Install Now**, then **Activate**.
3. Go to **Wrenio Studio → Wrenio Media Offload**, open the **Settings** tab, and enter your Cloudflare R2 credentials. (Recommended: define them in `wp-config.php` instead — see the "Credentials" block in the Description above.)
4. Click **Test Connection** to verify the bucket is reachable, then **Test Write Access** to verify your API token can PUT and DELETE.
5. Enable **URL Rewrite** once both tests pass.
6. Open the **Bulk Sync** page and run a bulk sync to migrate your existing media.
7. Only after bulk sync reaches 100% and spot checks pass, consider enabling **Delete Local Files** under the Features tab.

== Frequently Asked Questions ==

= What happens to the local file when upload succeeds? =

By default, nothing. The local file stays on the server as a backup. Enable **Delete Local Files** under Features to delete after a successful upload — but only once you've fully verified your R2 copy.

= What file types are allowed? =

Images (jpeg, png, gif, webp, svg, bmp, tiff, avif), video (mp4, mov, avi, mpeg, webm, ogv), audio (mp3, ogg, wav, m4a, flac, aac), and PDF. Files up to 50 MB are supported.

= Does it work with multi-site? =

Yes, on a per-site basis. Each site stores its own settings and syncs to its own bucket.

= What if reconciliation fails partway through? =

The tool processes attachments atomically: for each item, it copies, verifies, updates meta, then deletes the old objects. If any step fails, the attachment is left in a recoverable state — re-running reconciliation picks up where it left off. A retry cap (3 attempts per attachment) prevents a single bad item from blocking the rest; capped items appear in the Status table and are skipped on subsequent runs. (Resetting the retry counter to re-attempt a capped item is a Pro feature.)

= Is this safe to run on a production site? =

The reconciliation and orphan-cleanup tools are destructive (Reconcile deletes old R2 objects after copying; Orphan Cleanup deletes objects it determines are unreferenced). Always:

1. Take a database backup.
2. Take (or accept loss of) an R2 bucket backup.
3. Run in **Dry Run** mode first (Reconcile) or **Scan + Preview** first (Orphan Cleanup).
4. Review the log output and/or spot-check preview URLs.
5. Only then run the live operation.

= Will ERROR logs always be written? =

Yes. ERROR and WARNING entries are always logged regardless of the Debug Logging setting. INFO and DEBUG require Debug Logging to be enabled.

== Screenshots ==

1. Settings — General tab. Configure R2 credentials here, or (recommended) define them in `wp-config.php`.
2. Settings — Features tab. Toggle URL rewriting, choose upload mode, enable delete-local-after-upload, and turn on debug logging.
3. Bulk Sync — migrate existing media to R2 in batches. Shows totals and per-run options.
4. R2 Reconcile — detects R2 object keys that have drifted from the file path WordPress expects, and previews the realignment in dry-run mode.
5. Filename Cleanup — detects attachments where the local filename and the R2 key disagree.
6. Orphan Cleanup — scans the bucket and identifies R2 objects no longer referenced by any attachment, with a reviewable preview list.

== Changelog ==

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
