WP Manifestindependent plugin directory
manifest / media / nandung-r2

Nandung R2 - Cloudflare R2 Storage

Seamlessly integrate your WordPress Media Library with Cloudflare R2 storage. Automatically upload, serve, and manage media files through R2's powerful and cost-effective object storage.

by Nandung Team · github.com/nandunkz/nandung-r2 · website

★ 2stars
0forks

Install

No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:

wp plugin install https://github.com/nandunkz/nandung-r2/archive/refs/heads/main.zip
Readme github.com/nandunkz/nandung-r2 ↗

Nandung R2 - WordPress Media Library with Cloudflare R2

for Developers, see README-DEV.md

Seamlessly integrate your WordPress Media Library with Cloudflare R2 storage. Automatically upload, serve, and manage media files through R2's powerful and cost-effective object storage.

🌟 Features

Core Features

  • 🚀 Automatic Upload - Media files automatically uploaded to R2 when added to Media Library
  • 🔄 URL Replacement - Serve media files directly from R2 CDN with automatic URL replacement
  • ⚡ Fast Migration - Bulk migrate existing media files between local storage and R2
  • 🎯 Bidirectional Sync - Transfer files from local to R2 or R2 back to local
  • 🔒 Secure - Built with WordPress security best practices
  • 🌍 Multilingual - Full support for English and Indonesian languages

Advanced Options

  • Auto-delete local files - Save disk space by removing local files after R2 upload
  • Srcset rewrite - Optimize responsive images with R2 URLs for all sizes
  • Role-based access - Control who can delete media files
  • Real-time testing - Test R2 connection before going live

Developer Friendly

  • Clean, well-documented code
  • Composer autoloading support
  • PSR-4 namespacing
  • Comprehensive error handling
  • Extensible architecture

📋 Requirements

  • WordPress: 5.0 or higher
  • PHP: 7.4 or higher
  • Cloudflare R2: Active account with configured bucket

PHP Extensions

  • curl - For R2 API communication
  • json - For data handling
  • mbstring - For string operations

🚀 Installation

Method 1: Manual Installation

  1. Download the plugin files
  2. Extract to wp-content/plugins/nandung-r2/
  3. Activate the plugin in WordPress Admin → Plugins
  4. Configure your R2 credentials in Settings

Method 2: WordPress Upload

  1. Go to Plugins → Add New
  2. Click Upload Plugin
  3. Choose the plugin ZIP file
  4. Click Install Now
  5. Activate the plugin

⚙️ Configuration

Step 1: Get Cloudflare R2 Credentials

1. Create R2 Bucket

  1. Log in to Cloudflare Dashboard
  2. Go to R2 section
  3. Click Create Bucket
  4. Enter bucket name (e.g., my-media-bucket)
  5. Choose location (optional)
  6. Click Create Bucket

2. Get Account ID

  1. In R2 dashboard
  2. Copy your Account ID (displayed at top)

3. Create API Token

  1. Click Manage R2 API Tokens
  2. Click Create API Token
  3. Select Read & Write permissions
  4. Click Create API Token
  5. Copy Access Key ID and Secret Access Key
  6. ⚠️ Save secret key immediately - it won't be shown again!

4. Get Public URL

  1. Go to your bucket settings
  2. Click Settings tab
  3. Under Public Access, click Connect Domain
  4. Add your custom domain or use R2.dev URL
  5. Copy the public URL (e.g., https://media.yourdomain.com)

Step 2: Configure Plugin

  1. Go to Nandung R2 → Settings
  2. Fill in your credentials:
    • Account ID: Your Cloudflare Account ID
    • Access Key ID: R2 API Access Key ID
    • Secret Access Key: R2 API Secret Access Key
    • Bucket Name: Your R2 bucket name
    • Public URL: Your R2 public access URL
  3. Click Save Settings
  4. Click Test Connection to verify

Step 3: Configure Advanced Options (Optional)

  1. Go to Nandung R2 → Advanced
  2. Configure options:
    • Delete local files after upload: Save disk space (⚠️ use with caution)
    • Enable srcset rewrite: Optimize responsive images
  3. Click Save Advanced Options

📖 Usage Guide

Uploading New Media

Automatic Upload (Recommended)

  1. Go to Media → Add New
  2. Upload your files normally
  3. Files are automatically uploaded to R2
  4. URLs are automatically replaced with R2 URLs

What Happens?

1. You upload image.jpg to WordPress
2. Plugin uploads to R2: bucket/2025/01/image.jpg
3. WordPress uses R2 URL: https://media.yourdomain.com/2025/01/image.jpg
4. Local file is kept (unless auto-delete is enabled)

Migrating Existing Media

Migrate All Media to R2

  1. Go to Nandung R2 → Tools
  2. In Migrate Media Files section
  3. Set Batch Size (default: 10)
  4. Click Migrate Local → R2
  5. Wait for migration to complete
  6. Check the log for details

Migrate from R2 to Local

  1. Go to Nandung R2 → Tools
  2. Click Migrate R2 → Local
  3. Files are downloaded from R2 to local storage
  4. Useful for backup or reverting

Testing Connection

Quick Test from Settings

  1. Go to Nandung R2 → Settings
  2. Scroll to Quick Actions
  3. Click Test Connection
  4. View detailed log output

Advanced Testing

  1. Go to Nandung R2 → Tools
  2. Click Test R2 Connection
  3. View comprehensive connection details:
    • Account ID verification
    • Bucket access check
    • Response time
    • Connection status

Scanning for Missing Files

If some files are missing R2 metadata:

  1. Go to Nandung R2 → Tools
  2. Click Scan Missing R2 Meta
  3. Plugin identifies files without R2 data
  4. Optionally re-upload missing files

🎛️ Advanced Features

Auto-Delete Local Files

⚠️ Important: Use with caution in production!

When to enable:

  • You need to save disk space
  • Your R2 connection is stable and reliable
  • You have backups elsewhere
  • You don't need local file access

How to enable:

  1. Go to Nandung R2 → Advanced
  2. Check Delete local file after upload
  3. Click Save Advanced Options

What happens:

  • After successful R2 upload, local file is deleted
  • Only R2 URL remains in database
  • Cannot be reversed automatically

Srcset Rewrite for Responsive Images

What is srcset? WordPress generates multiple image sizes (thumbnail, medium, large) and uses srcset attribute for responsive images.

When to enable:

  • All image sizes are uploaded to R2
  • You want full CDN performance
  • Your theme uses responsive images

How to enable:

  1. Go to Nandung R2 → Advanced
  2. Check Enable srcset rewrite
  3. Click Save Advanced Options

Example:

<!-- Before -->
<img srcset="
  /wp-content/uploads/2025/01/image-300x200.jpg 300w,
  /wp-content/uploads/2025/01/image-768x512.jpg 768w,
  /wp-content/uploads/2025/01/image-1024x683.jpg 1024w
">

<!-- After -->
<img srcset="
  https://media.yourdomain.com/2025/01/image-300x200.jpg 300w,
  https://media.yourdomain.com/2025/01/image-768x512.jpg 768w,
  https://media.yourdomain.com/2025/01/image-1024x683.jpg 1024w
">

Batch Size Configuration

Control migration speed and server load:

  • Small (5-10): Safer for large files or slow connections
  • Medium (10-25): Balanced performance
  • Large (25-50): Faster but more resource intensive

Recommendation:

  • Start with default (10)
  • Increase gradually if no issues
  • Monitor server performance

🔧 Troubleshooting

Connection Failed

Symptoms:

  • "Connection failed" message
  • Unable to upload to R2
  • Test connection fails

Solutions:

  1. Check credentials - Verify Account ID, Access Key, Secret Key
  2. Check bucket name - Must match exactly (case-sensitive)
  3. Check API token permissions - Must have Read & Write access
  4. Check public URL - Must be valid and accessible
  5. Check firewall - Ensure WordPress can make outbound HTTPS requests

Files Not Uploading

Symptoms:

  • Files upload to WordPress but not R2
  • No R2 URL in database
  • Missing metadata

Solutions:

  1. Test connection - Use Tools → Test R2 Connection
  2. Check PHP memory - Large files need more memory
  3. Check file permissions - WordPress must be able to read files
  4. Check error logs - Look in wp-content/debug.log

URLs Not Rewriting

Symptoms:

  • Files on R2 but still showing local URLs
  • Old URLs in content

Solutions:

  1. Check R2 metadata - Use Tools → Scan Missing R2 Meta
  2. Regenerate metadata - Re-upload files if needed
  3. Clear cache - If using caching plugin
  4. Check public URL - Must be correctly configured

Migration Stuck

Symptoms:

  • Migration stops mid-process
  • Progress bar doesn't move
  • Timeout errors

Solutions:

  1. Reduce batch size - Try smaller chunks (5-10)
  2. Check server resources - CPU, memory, disk space
  3. Increase PHP limits - max_execution_time, memory_limit
  4. Check network - Ensure stable connection to Cloudflare

Performance Issues

Symptoms:

  • Slow upload speed
  • Timeouts during migration
  • High server load

Solutions:

  1. Reduce batch size - Process fewer files at once
  2. Optimize images - Compress before upload
  3. Upgrade hosting - Consider more powerful server
  4. Use off-peak hours - Migrate during low traffic

📊 Statistics & Monitoring

Dashboard Overview

Go to Nandung R2 → Tools to view:

  • Total Attachments: All media files in library
  • On R2: Files successfully uploaded to R2
  • Missing R2 Meta: Files without R2 metadata

Migration Log

Real-time log shows:

  • Files processed
  • Success count
  • Skipped count
  • Error messages
  • Processing time

Connection Log

Detailed connection test output:

  • Account ID verification
  • Bucket name confirmation
  • Response time measurement
  • Connection status
  • Error details (if any)

🌍 Multi-Language Support

Available Languages

  • English (en_US) - Default
  • Bahasa Indonesia (id_ID) - Complete translation

Change Language

  1. Go to Settings → General
  2. Select Site Language
  3. Choose your preferred language
  4. Save changes
  5. Reload plugin pages

Add New Language

See languages/README.md for translation guide.

🔐 Security

Data Protection

  • API credentials encrypted at rest
  • Nonce verification on all AJAX requests
  • Capability checks for all actions
  • Input sanitization and validation
  • Output escaping for all display

Best Practices

  1. Use strong API tokens - Generate unique tokens
  2. Limit permissions - Only grant necessary access
  3. Regular backups - Backup before major changes
  4. Monitor logs - Check for suspicious activity
  5. Keep updated - Install plugin updates promptly

🆘 Support & Resources

Documentation

  • Plugin Settings: Nandung R2 → Settings → About
  • Translation Guide: languages/README.md
  • Developer Guide: README-DEV.md

Getting Help

Before Asking for Help:

  1. Check this README
  2. Test your R2 connection
  3. Check WordPress debug log
  4. Try with default WordPress theme
  5. Disable other plugins temporarily

Where to Get Help:

When Reporting Issues, Include:

  • WordPress version
  • PHP version
  • Plugin version
  • Error messages (from debug log)
  • Steps to reproduce
  • Screenshots (if relevant)

🎯 Performance Tips

Optimization Strategies

  1. Use CDN custom domain

    • Better branding
    • Improved caching
    • Faster DNS resolution

  2. Enable srcset rewrite

    • Responsive images from R2
    • Better mobile performance
    • Reduced bandwidth

  3. Optimize images before upload

    • Compress images
    • Convert to WebP
    • Resize appropriately

  4. Use auto-delete wisely

    • Save server disk space
    • Reduce backup size
    • Ensure R2 reliability first

  5. Migrate in batches

    • Don't overload server
    • Monitor during migration
    • Use off-peak hours

📝 Changelog

Version 1.0.0 (2025-01-05)

  • 🎉 Initial release
  • ✅ Automatic R2 upload on media library add
  • ✅ URL replacement for R2-hosted files
  • ✅ Bidirectional migration (Local ↔ R2)
  • ✅ Connection testing with detailed logs
  • ✅ Advanced options (auto-delete, srcset rewrite)
  • ✅ Multi-language support (English, Indonesian)
  • ✅ Role-based access control
  • ✅ Comprehensive error handling

📜 License

This plugin is licensed under the GPL v2 or later.

Copyright (C) 2025 Nandung

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

🙏 Credits

Built With

Contributors

  • Nandung Team - Initial development

Special Thanks

  • Cloudflare for R2 storage platform
  • WordPress community for excellent documentation

🔗 Links

Made with ❤️ by Nandung

For developer documentation, see README-DEV.md