=== Uploads Relay for Local Development by Carl Alberto ===
Contributors: carl-alberto
Tags: development, uploads, proxy, local, media
Requires at least: 6.0
Tested up to: 7.0
Stable tag: 1.0.0
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Proxy missing upload files from a remote server during local development. No need to download the entire uploads folder.

== Description ==

**Uploads Relay** makes local WordPress development easier and lightweight by automatically proxying missing upload files from a remote server. No need to download gigabytes of media just to work on a site locally.

= Features =

* **Proxy Missing Files** — Automatically serve missing upload files from a remote server.
* **Always Remote Mode** — Rewrite all upload URLs to point to the remote server for the fastest setup.
* **Optional Local Caching** — Cache proxied files locally so subsequent requests are served from disk.
* **Security First** — Path traversal protection, host allowlisting, and file extension validation.
* **Environment Guard** — Only active when WordPress environment type is set to "local".
* **Zero Configuration on Remote** — No changes needed on the remote/production server.

= How It Works =

1. A visitor or developer requests an upload file (e.g., an image in a post).
2. If the file does not exist locally, WordPress returns a 404.
3. The plugin intercepts the 404, fetches the file from the configured remote server, and serves it.
4. Optionally, the file is cached locally for faster subsequent loads.

= Use Cases =

* Local development of large WordPress sites without syncing media.
* Staging environments with partial media libraries.
* Quick site clones for debugging or testing.

= Requirements =

* WordPress 6.0 or higher
* PHP 7.4 or higher
* `WP_ENVIRONMENT_TYPE` must be set to `local` (the plugin will not function in production environments)

= External Service =

This plugin sends HTTP requests to a **remote server that you configure yourself** in order to fetch upload files missing from your local environment. **No requests are made until you explicitly enter a remote URL and enable the proxy in Settings → Uploads Relay.** By enabling the plugin and providing a remote URL, you consent to these requests being made.

* **What is sent:** HTTP GET requests for specific media file paths (e.g., `/wp-content/uploads/2024/01/photo.jpg`).
* **When it is sent:** Only when a requested upload file does not exist locally, the proxy is enabled, and the environment type is `local`.
* **Where it is sent:** Only to the remote server URL you have configured. This is typically your own production or staging server.
* **No data is collected, stored, or transmitted** to any third-party service, analytics provider, or external server other than the one you configure.
* **No telemetry, tracking, or usage data** is collected by this plugin.

Since the remote server is your own, its terms of service and privacy policy are governed by your own hosting provider.

== Installation ==

1. Upload the `uploads-relay-crax` folder to `/wp-content/plugins/`.
2. Activate the plugin through the "Plugins" menu in WordPress.
3. Go to **Settings → Uploads Relay**.
4. Enter the remote uploads URL (e.g., `https://example.com/wp-content/uploads`).
5. Choose your preferred mode and enable the proxy.

== Frequently Asked Questions ==

= Does this plugin work in production? =

No. The plugin is designed exclusively for local development and will only function when `wp_get_environment_type()` returns `local`. This is a safety measure to prevent unintended use in production.

= What is the difference between the two modes? =

**Proxy only when missing locally** keeps your local upload URLs intact and only fetches from the remote server when a file is not found locally. This is the recommended mode for most use cases.

**Always rewrite URLs to remote** changes all upload URLs site-wide to point to the remote server. This is the fastest option but means all media is loaded from the remote server, even if files exist locally.

= Does the remote server need any special configuration? =

No. The plugin simply requests files from the remote server's uploads URL. As long as the files are publicly accessible, no changes are needed on the remote server.

= Will cached files count toward my local disk space? =

Yes. When caching is enabled, proxied files are saved to your local `wp-content/uploads/` directory. You can set a maximum cache size in megabytes to limit disk usage.

= Does this plugin collect any data or contact external services? =

No. The plugin does not collect any user data, usage statistics, or telemetry. The only external requests it makes are HTTP GET requests to the remote server URL that you configure in the plugin settings. No requests are made until you explicitly enable the proxy and provide a URL.

= What file types are supported? =

By default, the plugin proxies common media file types: JPG, JPEG, PNG, GIF, WebP, SVG, PDF, MP4, MP3, DOC, DOCX, and ZIP. You can customize the allowed extensions in the settings.

== Changelog ==

= 1.0.0 =
* Initial release.
* Proxy missing uploads from a remote server.
* Always remote URL rewrite mode.
* Optional local caching with size limits.
* Admin settings page.
* Environment type guard (local only).
* Path traversal and extension validation.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
