Divine Apparitions Uploads Proxy

When you pull a production database into a staging or local environment, every media URL points at a file you didn’t copy — pages render with broken images and dead file links. Divine Apparitions Uploads Proxy intercepts the request for any missing uploads file and resolves it against a configured production Origin, so pages render with real media without syncing the entire uploads directory.

Because it works at the request level — hooking template_redirect when the web server routes a missing file to index.php (nginx try_files, used by DDEV, Lando, and Pantheon) — it catches every missing upload, including images embedded directly in post content, size derivatives, and srcset candidates, not just the URLs WordPress generates for attachments.

It resolves a missing file in one of two modes:

• Download mode (default): streams the file from the Origin, saves it into the local uploads directory, and serves it. Every later request is served by the web server, so your local site accumulates exactly the subset of media your tests actually touch — never the whole uploads folder.
• Hotlink mode (opt-in): issues a temporary redirect to the file on the Origin, writing nothing locally.

Configuration lives in wp-config constants / environment variables (with a database-option fallback), so it survives every database pull and configures itself hands-free in CI. The plugin is inert on production and stays off until an Origin is configured.

Features:

• Request-level interception — resolves content-embedded images, derivatives, and srcset, not just attachment URLs.
• Download or Hotlink mode, chosen per environment.
• Optional Basic Auth for fetching from a locked Test/Dev Origin.
• Negative cache so a file genuinely missing on the Origin stops re-hitting it, while transient errors (5xx/timeout) retry on the next request.
• Write hardening: executable file types are refused and paths are contained to the uploads directory.
• Diagnostics settings page showing the effective config and its source, the counters, and a “test Origin connection” button.
• wp uploads-proxy WP-CLI command (status / clear-cache) for scripting setup and reset in CI.
• Inert on production; off until an Origin is configured.