Media Replacement - Replace WordPress media without breaking your links

Introduction

We've all been there: a badly retouched image, an obsolete PDF, a video compressed too hard... but already inserted all over the site. Deleting then re-importing breaks URLs, leaves pages with dead links, and changes the media ID.
The module Media Replacement of WPMasterToolKit solves this problem: it replaces the source file media without changing its ID, file name or publication date. Result : all URLs and integrations remain valid.

Which plugins can this module replace?

Relevant if you use a dedicated plugin such as "Enable Media Replace". This module offers the same logic (in-place replacement) but integrated natively into WPMasterToolKit, with no additional plug-ins required.

Exactly what the module does

• In-place replacement copy your new file over the existing file on the disc.
• Identity preserved : ID, slug/filename and date remain the same - so no URL changes.
• Regenerated miniatures After replacement, the module restarts wp_generate_attachment_metadata() for recreate all undersizes (thumbnails).
• Strict type checking the new file must have the same MIME type (e.g. JPG → JPG, PDF → PDF). This avoids inconsistencies and integration problems.
• Visual overview an admin-side interface for viewing information "Current vs. "New (type, size, width/height for images) before validation.
• Reliable cleaning of old files deletion of existing files and sub-sizes, including images -scaled. If a plugin (e.g. multilingual) blocks deletion, a "hard delete makes sure to wipe off any leftovers.
• Natural integration into the admin :
  • Button "Replace media in the line actions of the Media library (list).
  • Button in the editing mode media.
  • Button in the Publish box (attachment editing screen).
  • An internal page (under Media) handles upload and confirmation - it is hidden from the menu to remain accessible only via action buttons.

UX details on the administration side

• Clear interface with two columns: Current vs. New.
• Drag & drop or click to select file.
• Immediate validation on the JS side (max site weight, same type), with localized messages.
• Replace" button disabled until validations are completed.

Scenarios and limits to be aware of

• Same type required : you can't replace a PNG with a JPG. Keeping the same format guarantees 0 case.
• File name retained : it's designed to keep exactly the same URL.
• CDN / cache After replacement, remember to purge cache if you use a CDN or aggressive caching.
• Dimensions if you import a larger/smaller image, the thumbnails will be regenerated accordingly (depending on your WordPress image sizes/theme).
• Permissions accessible to roles with upload_files.
• Security everything is protected by nonce and controls on the uploaded file (is_uploaded_fileauthorized types, max WordPress size).

How to use this module

1. Go to Media → Library.
2. On the media line to be replaced, click Replace media (or open the media file and click the same button).

   

3. Drag and drop the new file (same type as the original).

   

4. Check info in preview "New".
5. Click Replace.
   That's all there is to it: URL does not changethe site continues to point to the same ID, but with the updated file.

   

Our technical choices (and why)

• Keep ID/path copy the new file on the original path (copy() → same name, same location). This is the only way to ensure that all links remain valid.
• Strict MIME validation comparison between the original MIME and that of the new file via wp_check_filetype_and_ext() and get_post_mime_type() to avoid surprises (embed, players, HTML tags, etc.).
• Robust cleaning we use wp_delete_attachment_files() with metadata and backup sizes, then a fallback physical deletion if necessary (in the case of images -scaled or multilingual plugins).
• Metadata regeneration : wp_generate_attachment_metadata() + wp_update_attachment_metadata() to recreate all sub-sizes immediately after replacement - no need for third-party tools.
• Experience admin buttons added via :
  • media_row_actions
  • attachment_fields_to_edit (for the modal)
  • attachment_submitbox_misc_actions (edit screen)
    A sub-menu page hidden is loaded on demand to display the replacement UI, with dedicated assets (CSS/JS) and localized strings.
• Safety & capacity :
  • Restricted access via upload_files.
  • Nonce for all URLs and forms.
  • Controls is_uploaded_filemanagement of upload errors, and respect for wp_max_upload_size() (via localized JS).
• Performance conditional asset loading only on the replacement page. If the module is not activated, nothing is loaded.

Conclusion

The module Media Replacement of WPMasterToolKit makes media replacement a simple safe, fast and without side effects : same ID, same URL, same datebut updated file and regenerated miniatures. No more broken links or the hassle of re-importing. It's the ideal tool for keeping media libraries clean and up-to-date, with complete confidence.