kaiseki/wp-replace-uploads-url

Rewrites local uploads URLs to a remote production URL on non-production WordPress environments

1.0.0 2026-06-01 06:17 UTC

Requires

• php: ^8.2
• kaiseki/config: ^2.0
• kaiseki/wp-env: ^1.0
• kaiseki/wp-hook: ^2.0
• psr/container: ^1.1 || ^2.0

Requires (Dev)

• bnf/phpstan-psr-container: ^1.1
• kaiseki/php-coding-standard: ^1.0
• maglnet/composer-require-checker: ^4.0
• php-stubs/wordpress-stubs: ^6.2
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^11.0
• roave/security-advisories: dev-latest
• szepeviktor/phpstan-wordpress: ^2.0

MIT

• Kaiseki

README

Rewrites local uploads URLs to a remote production URL on non-production WordPress environments.

On local and staging environments, media in the database often points at uploads that only exist on production. This serves those files from the production URL instead — rewriting attachment src, srcset, the media-library JS payload and post content — so you don't have to sync the uploads directory. It is a no-op on production and whenever no remote URL is configured. Wired as a kaiseki/wp-hook HookProviderInterface through ConfigProvider.

Installation

composer require kaiseki/wp-replace-uploads-url

Requires PHP 8.2 or newer.

Usage

Register ConfigProvider with your laminas-style config aggregator and set the production uploads URL via the replace_uploads_url config key:

use Kaiseki\WordPress\ReplaceUploadsUrl\ReplaceUploadsUrl;

return [
    'replace_uploads_url' => 'https://www.production-site.com/wp-content/uploads',
    'hook' => [
        'provider' => [
            ReplaceUploadsUrl::class,
        ],
    ],
];

The remote URL can also be supplied through the REPLACE_UPLOADS_URL constant (e.g. defined in wp-config.php), which takes precedence over the config value:

define('REPLACE_UPLOADS_URL', 'https://www.production-site.com/wp-content/uploads');

Production is detected through kaiseki/wp-env's EnvironmentInterface: when isProduction() is true the filters are never registered, so production output is left untouched.

Development

composer install
composer check   # check-deps, cs-check, phpstan

License

MIT — see LICENSE.