Media Entity File Replace
Allows content editors to replace source files associated with file-based media entities while preserving the original filename and path.
media_entity_file_replace
Install
composer require 'drupal/media_entity_file_replace:8.x-1.3'
composer require 'drupal/media_entity_file_replace:8.x-1.2'
composer require 'drupal/media_entity_file_replace:8.x-1.0'
Overview
Media Entity File Replace provides a streamlined workflow for content editors who need to update files attached to media entities without changing URLs or breaking existing links. When a document, image, audio file, or other file-based media needs to be updated, this module allows the new file to completely overwrite the existing one, maintaining the same filename and filesystem path.
This is particularly valuable in scenarios where files have been shared via direct links, embedded in emails, or referenced in print materials. Instead of uploading a new file (which would create a new URL), editors can replace the file contents while keeping everything else intact.
The module adds a "Replace file" form widget to media edit forms, which can be enabled per media type through the form display configuration. It intelligently handles content translations, preventing accidental overwrites of files shared between language versions.
Features
- Adds a 'Replace file' widget to media entity edit forms for file-based media types (Document, Image, Audio, Video, etc.)
- Two replacement modes: overwrite original file (preserves filename and path) or use replacement filename (creates new file reference)
- Enforces same file extension when overwriting to ensure proper MIME type handling by web servers
- Automatically flushes image style derivatives when image files are replaced, ensuring thumbnails and styled images are regenerated
- Intelligently handles content translations - prevents replacement widget from appearing when it would affect the default language file
- Inherits upload validators from the source field (file size limits, allowed extensions) and displays them to users
- Hides the 'Remove' and 'Upload' buttons on the standard file widget when replacement widget is enabled, preventing conflicting workflows
- Validates that replacement files meet all original field requirements before processing
- Maintains proper file usage tracking - old files referenced only by previous revisions are automatically marked for cleanup
Use Cases
Updating a PDF document while preserving shared links
A company has a product catalog PDF that has been shared via email and linked from multiple web pages. When a new version of the catalog is ready, the content editor can use the Replace file widget to upload the new PDF. By checking 'Overwrite original file', the new content replaces the old file while keeping the exact same URL, so all existing links continue to work and visitors automatically get the updated document.
Refreshing product images without breaking cache
An e-commerce site needs to update product photos. Using the file replacement feature with 'Overwrite original file' checked, editors can replace images while maintaining the same file path. The module automatically flushes image style derivatives, ensuring that thumbnails and other styled versions are regenerated with the new image content.
Changing a document to a completely new file
When a document is being replaced with something entirely different (e.g., replacing a draft with a final version that has a different filename), uncheck the 'Overwrite original file' option. This uploads the replacement as a new file, updates the media entity to reference it, and allows the old file to be cleaned up if no other content references it.
Managing translated media with separate files per language
For a multilingual site where document translations are stored as separate files, the module intelligently handles replacements. When a media entity has translations with different files, editors can safely replace the file for one language without affecting other translations. The module prevents the replacement widget from appearing when using it would accidentally modify the default language's file.
Tips
- Place the 'Replace file' widget directly beneath the standard File or Image widget in the form display for intuitive editing flow
- When overwriting the original file, the replacement must have the same file extension (e.g., you cannot replace a .pdf with a .docx)
- The module respects all upload validators from the original field, including file size limits and allowed extensions
- If you need to change file types, uncheck 'Overwrite original file' to upload as a new file instead
- For image media, image style derivatives are automatically flushed when files are replaced, so regeneration happens on next request
- The replacement widget only appears when editing existing media - it is hidden on the 'Add media' form since there is nothing to replace yet
- If the source file has been deleted from the filesystem, the replacement widget will not appear until a file is re-attached
Technical Details
Admin Pages 1
/admin/structure/media/manage/{media_type}/form-display
Configure the form display for a media type to enable or disable the file replacement widget. The 'Replace file' pseudo-field appears in the list of available form components for file-based media types (those using File, Image, Audio, or Video source plugins). Drag it from the 'Disabled' section to the main form area to enable file replacement functionality for that media type.
Hooks 3
hook_help
Provides help text for the module's help page, explaining how to enable and use the file replacement feature.
hook_entity_extra_field_info
Declares the 'replace_file' pseudo-field for form displays on all file-based media types. This pseudo-field allows site builders to enable or disable the file replacement widget through the standard form display configuration interface.
hook_form_BASE_FORM_ID_alter (media_form)
Alters the media entity edit form to add the file replacement widget when configured. Adds a fieldset containing a file upload field and checkbox for controlling replacement behavior. Also adds custom validation and submit handlers, and hides the standard file widget's Remove/Upload buttons.
Troubleshooting 5
Ensure you have enabled the widget in the form display configuration. Go to Administration > Structure > Media types > [Your Media Type] > Manage form display, and drag 'Replace file' from the Disabled section into the Content region.
This is expected behavior. The module only adds the replacement widget for file-based media types (those using File, Image, Audio, or Document source plugins). Remote Video uses an oEmbed source which does not have a file to replace.
When overwriting the original file, the replacement must have the same extension to ensure web servers serve the correct MIME type. Uncheck 'Overwrite original file' to upload a file with a different extension.
This is intentional when the translation uses the same file as the default language. Showing the widget would risk replacing the file for all languages. Upload a different file for the translation first, then the replacement widget will appear.
When using 'Overwrite original file', the same file entity is kept and its contents are replaced. When not overwriting, the old file remains if other revisions still reference it. Files are only deleted by cron when nothing references them.
Security Notes 3
- The module relies on existing Drupal media permissions - users need 'administer media' or appropriate media type edit permissions to access the replacement functionality
- File upload validators from the source field are enforced, preventing upload of disallowed file types
- The module does not introduce any new permission - access is controlled by standard media entity access