=== Bromate Remote Media Bridge ===
Contributors: Sophabed
Tags: media, attachments, staging, development, sync
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Use a remote WordPress uploads directory without copying your entire media library. Optionally cache media files locally as visitors browse your site.

== Description ==

Bromate Remote Media Bridge helps WordPress installations share the same database across multiple environments without requiring a full copy of the uploads directory.

Instead of synchronizing gigabytes of media files between environments, the plugin allows WordPress to use a remote uploads directory while keeping the local media library structure intact.

The plugin can:

* Rewrite attachment URLs generated by WordPress.
* Rewrite responsive image URLs in srcset attributes.
* Redirect media requests to a remote uploads directory.
* Progressively cache remote media files locally while visitors browse your site.
* Reduce deployment complexity for large media libraries.

This is particularly useful for:

* Local development environments using a production database.
* Staging and pre-production environments.
* WordPress redesign and migration projects.
* Large sites where synchronizing the entire uploads directory is impractical.
* Long-running projects where the production media library changes frequently.

== Example ==

A local site generates:

`https://local.example.test/wp-content/uploads/2026/05/image.jpg`

Bromate Remote Media Bridge rewrites it to:

`https://production.example.com/wp-content/uploads/2026/05/image.jpg`

When "Download while navigating" is enabled, the file may also be downloaded automatically and stored locally the first time it is requested.

This creates a progressively warmed local media cache containing only the files that have actually been viewed.

== Features ==

* Rewrite WordPress attachment URLs.
* Rewrite responsive image URLs (srcset).
* Redirect direct media requests.
* Progressive local media caching while browsing.
* Automatic local storage of viewed remote media files.
* Excluded URL support.
* Environment-specific configuration through constants.
* Optional debug logging.
* No custom database tables.
* No front-end assets.
* Works with shared databases across development, staging and production environments.

== Installation ==

1. Upload the plugin through the WordPress Plugins screen or install it manually.
2. Activate the plugin.
3. Navigate to Settings > Remote Media Sync.
4. Enable media URL rewriting.
5. Configure the remote uploads base URL.
6. Optionally enable "Download while navigating".

== Configuration ==

The remote uploads URL should point directly to the uploads directory of the environment containing the media files.

Example:

`https://www.example.com/wp-content/uploads`

You may also configure the plugin using constants in wp-config.php:

`define( 'BROMATE_REMOTE_MEDIA_BRIDGE_ENABLED', true );`

`define( 'BROMATE_REMOTE_MEDIA_BRIDGE_BASE_URL', 'https://www.example.com/wp-content/uploads' );`

`define( 'BROMATE_REMOTE_MEDIA_BRIDGE_DOWNLOAD_WHILE_NAVIGATING', true );`

`define( 'BROMATE_REMOTE_MEDIA_BRIDGE_DEBUG', false );`

Constants take precedence over saved settings.

== Frequently Asked Questions ==

= Does this copy media files? =

Not by default.

The plugin primarily rewrites URLs and redirects requests to a remote uploads directory.

If "Download while navigating" is enabled, media files can be progressively cached and stored locally as they are viewed.

= Does this work with very large media libraries? =

Yes.

The plugin was designed specifically for environments where synchronizing the entire uploads directory would be impractical or unnecessary.

= Is Download while navigating a full media synchronization tool? =

No.

The feature progressively builds a local cache of media files that have actually been viewed. It is intended to reduce storage requirements and simplify development workflows, not to guarantee a complete copy of the remote media library.

For complete migrations, a dedicated media migration workflow may still be required.

= Does this work with CDNs? =

Yes.

Any uploads-compatible URL can be used, including CDN endpoints.

= Does this work when the web server returns a 404 before WordPress loads? =

URL rewriting still works because URLs are generated by WordPress.

Direct media redirects require the request to reach WordPress. If your server handles missing files before WordPress loads, additional server configuration may be required.

= Why are media files not downloading locally? =

Some servers, CDNs, security services, anti-hotlinking protections or rate-limiting rules may block automated server-to-server downloads.

In these situations URL rewriting still works, but local media caching may be limited or unavailable.

== Screenshots ==

1. Remote Media Sync settings page.
2. Remote uploads URL configuration.
3. Download while navigating option.

== Changelog ==

= 1.0.0 =

* Initial public release.
* Remote media URL rewriting.
* Upload request redirection.
* Progressive local media caching.
* Excluded URL support.
* Environment-specific configuration.
* Optional debug logging.
