☁️ WP Cloud Offloader

Seamlessly offload WordPress media library assets to S3-compatible cloud storage and deliver them via CDN while slashing local server storage usage.

---

🚀 Overview

WP Cloud Offloader is a commercial-grade WordPress plugin designed to offload images, videos, audio, and documents to S3-compatible cloud object storage. Serving your media from cloud storage or a global CDN keeps your web server lightweight, slashes hosting costs, speeds up page load times, and accelerates site backups.

---

✨ Key Features

Feature	Description
🌐 Multi-Cloud Storage	Native integration with Amazon S3, Cloudflare R2 (Zero Egress), DigitalOcean Spaces, Backblaze B2, Wasabi, and MinIO.
⚡ Automatic Offloading	Instantly uploads newly added WordPress media and generated thumbnail sizes to cloud storage upon upload.
📦 Bulk Media Migration	Migrate existing Media Libraries in bounded background batches with live progress tracking, ETA countdown, and speed throughput metrics.
🧹 3 Retention Policies	Choose between Retain Local Files, Smart Local Cleanup (frees ~80% disk space while saving original backup), or Full Cloud Migration.
🔗 Dynamic URL Rewriting	Automatically rewrites attachment URLs, responsive srcset image attributes, and inline post content images to your CDN domain.
💧 Cloud Hydration	Temporarily restores cloud-only originals on demand when WordPress core or image editors request source files, then safely cleans up.
🛠️ Image Editor & Crop Support	Fully supports WordPress image crop, rotate, restore, and thumbnail regeneration plugins without breaking cloud URLs.
🖥️ WP-CLI Support	Scriptable background migration commands (wp wpco offload) for enterprise sites with 50,000+ attachments.
🔒 Isolated AWS SDK	Bundled using PHP-Scoper under WPCloudOffloader\Aws\* to prevent conflicts with other plugins using AWS SDK.
🧩 Ecosystem Compatibility	Works out-of-the-box with WooCommerce, Elementor, Modern Image Formats (WebP, AVIF), Imagify, and EWWW Image Optimizer.

---

☁️ Supported Cloud Storage Providers

Cloud Provider	Feature Highlights	Egress Fees
Amazon S3	Industry-standard object storage & CloudFront CDN integration	Standard AWS Pricing
Cloudflare R2	S3-compatible storage with zero egress bandwidth fees	$0 / GB Egress
DigitalOcean Spaces	Simple object storage with built-in CDN delivery	Low-cost bundling
Backblaze B2	High-reliability, low-cost S3-compatible storage	Highly affordable
Wasabi	High-performance hot cloud storage with no API request fees	Predictable flat-rate
MinIO / Custom S3	Any self-hosted MinIO server or custom S3 endpoint (OVH, Linode, Scaleway)	Self-managed

---

🏗️ Architecture & How It Works

                                  ┌──────────────────────────┐
                                  │   Cloud Storage Bucket   │
                                  │ (AWS S3 / R2 / Spaces)   │
                                  └─────────────┬────────────┘
                                                │
 ┌──────────────────┐     Upload     ┌──────────▼───────────┐     CDN Delivery     ┌──────────────────┐
 │  WordPress User  ├───────────────►│  WP Cloud Offloader  ├────────────────────►│  Website Visitor │
 │ (Uploads Media)  │                │   (URL Rewriting)    │                     │ (Fast Image Load)│
 └──────────────────┘                └──────────────────────┘                     └──────────────────┘

1. Upload: Media uploaded via Admin panel, WooCommerce, or REST API is intercepted.
2. Cloud Transfer: Original media and generated sub-sizes are transferred to cloud storage.
3. Retention Policy Applied: Local disk copy is retained or cleaned up according to your configured policy.
4. URL Rewriting: WordPress attachment URLs and srcset attributes are automatically rewritten to your CDN or custom domain.

---

💻 Installation & Quick Start

1. Download / Install:

   git clone https://github.com/themubiin/wp-cloud-offloader.git wp-cloud-offloader

2. Activate: Activate WP Cloud Offloader via the WordPress Plugins menu.
3. Run Setup Wizard:
   • Open WP Cloud Offloader in the WordPress admin sidebar.
   • Select your cloud provider (e.g. Amazon S3, Cloudflare R2).
   • Enter Access Keys, Secret Keys, Region, and Bucket name.
   • Click Save & Test Connection to verify API access.
4. Configure Retention & Delivery:
   • Set custom CDN domain (e.g., https://cdn.mysite.com).
   • Choose your file retention policy.
5. Bulk Migration (Optional):
   • Navigate to Media & Offloading and click Start Bulk Offload to migrate your existing library.

---

🖥️ WP-CLI Commands

For large media libraries (50,000+ attachments), run background offload operations directly from your terminal:

# Run bulk offload for all pending attachments
wp wpco offload

# Force re-offloading of all media attachments
wp wpco offload --force

# Specify custom batch size
wp wpco offload --batch-size=50

---

⚙️ wp-config.php Environment Override

Store credentials securely in wp-config.php to prevent storing secret keys in the WordPress database:

// AWS S3 / Cloud Provider Credentials
define('WPCO_AWS_KEY', 'your-access-key-id');
define('WPCO_AWS_SECRET', 'your-secret-access-key');

// Custom Provider Endpoints (e.g., Cloudflare R2 or MinIO)
define('WPCO_AWS_ENDPOINT', 'https://<account-id>.r2.cloudflarestorage.com');

---

🔌 Developer Action & Filter Hooks

WP Cloud Offloader provides 20+ extensible hooks for developers:

1. Skip Offloading Specific Files

add_filter('wpco_should_offload_attachment', function($should_offload, $attachment_id) {
    $file = get_attached_file($attachment_id);
    // Skip files larger than 10MB
    if ($file && filesize($file) > 10 * 1024 * 1024) {
        return false;
    }
    return $should_offload;
}, 10, 2);

2. Custom Bucket Path Prefix

add_filter('wpco_cloud_path_prefix', function($prefix, $attachment_id) {
    return 'custom-client-media/' . date('Y/m/');
}, 10, 2);

3. Modify S3 Client Constructor Arguments

add_filter('wpco_s3_client_args', function($args, $provider_key) {
    $args['http']['timeout'] = 30;
    return $args;
}, 10, 2);

---

🧪 Testing & Verification

The plugin includes an automated functional and UI rendering test suite:

# Run production functional audit suite
php scratch/test_functional_audit.php

# Verify UI template rendering
php scratch/test_ui_render.php

---

🌐 Connect & Socials

• GitHub Repository: github.com/themubiin/wp-cloud-offloader
• Support Email: mubin@webdextro.org
• Website: mubin.me
• Facebook: facebook.com/the.mubiin
• LinkedIn: linkedin.com/in/mubiiin
• GitHub Profile: github.com/themubiin

---

📄 License & Attribution

Distributed under the GPLv2 or later License. See LICENSE for more information.

• Author: Muntasir Mubin
• Website: mubin.me
• Company: WebDextro
• Support: mubin@webdextro.org

---

Made with ❤️ by Muntasir Mubin