Documentation

Everything you need to install and use Smart Media Replacer.

Getting Started

Requirements

  • ✓ WordPress 5.0+
  • ✓ PHP 7.4+
  • ✓ Standard WordPress Media Library
  • ✓ No API keys, no external services, no configuration

Installation

  1. 1Purchase and download the .zip from for-wordpress.org
  2. 2WP Admin → Plugins → Add New → Upload Plugin
  3. 3Upload the .zip → Install Now → Activate
  4. 4Open Media Library — the Replace Media action appears automatically on each item

Using Replace Media

  1. 1Go to WP Admin → Media Library
  2. 2Switch to List view (the grid view also works)
  3. 3Hover over any file — click "Replace Media" in the action row
  4. 4In the modal that opens, click Choose File or drag the new file
  5. 5Click Replace
  6. 6The plugin processes the replacement — this takes 2–10 seconds depending on image size and number of thumbnail sizes
  7. 7Done — the file has been replaced. Refresh the page to see the new version.

How It Works

File Replacement

The plugin uploads the new file to a temporary location, validates it, then copies it to the exact path of the original file — overwriting it. The attachment URL in WordPress remains unchanged because the file lives at the same path.

Thumbnail Regeneration

WordPress stores multiple sizes of every image (thumbnail, medium, large, and any custom sizes registered by your theme or plugins). After replacing the source file, Smart Media Replacer deletes all existing thumbnail files and regenerates them from the new source. This ensures every size shows the new image.

Database Updates

The plugin updates the attachment record in wp_posts (GUID, MIME type) and any related records in wp_postmeta (file metadata, image dimensions). This keeps WordPress metadata consistent with the actual file.

Extension Changes

If you replace a JPG with a PNG, the file extension changes. The plugin detects this and searches wp_posts and wp_postmeta for references to the old extension, updating them to the new one. This prevents references to a file path that no longer exists.

Security

  • ✓Nonce verification — every replacement request includes CSRF protection
  • ✓Capability check — only users with upload_files permission can replace media
  • ✓File type validation — runs before the upload is accepted
  • ✓Prepared statements — all database operations use SQL injection protection
  • ✓Output escaping — all output is XSS-safe
  • ✓File permission checks — run before any write operation

Changelog

v1.0.0 — April 2026
Initial release
  • Replace Media action in Media Library
  • Automatic thumbnail regeneration
  • Database reference updates (wp_posts, wp_postmeta)
  • Extension change detection and reference update
  • CSRF protection with nonce verification
  • Capability check (upload_files)
  • AJAX-powered upload