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

☁️ Supported Cloud Storage Providers

🏗️ 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