How to Replace Files in Drupal

Don’t forget to subscribe to our YouTube channel to stay up-to-date.

Drupal doesn’t support the ability to replace existing files. You can create and delete files, but you can’t replace a file without using a module. If you try to upload a file with the same name Drupal will append “_0”, “_1”, etc… to the filename and increment it.

Luckily two modules can help with replacing files, and they’re called Media Entity File Replace and File Replace.

What is the main difference between Media Entity File Replace and File Replace?

Both modules will replace “files” whilst retaining the original file’s filename by performing an “overwrite” function in the backend. In Drupal, an uploaded “file” can be a “media entity” or a “file entity”.

As the module names suggest, the main difference is that Media Entity File Replace works at the media entity level, whereas File Replace works at the file entity level.

Media Entity File Replace

This module allows editors to replace files at the media entity level by overwriting the existing media files. Because it overwrites the files, the filename and path are exactly retained.

You should use this module to allow content editors to replace media entity files whilst keeping the same filename and path as the original file.

Getting Started

1. Download and enable the module. This module requires no additional libraries and can simply be installed with composer which is the recommended way.

To install using Composer:

composer require drupal/media_entity_file_replace

If you get the following error when using Composer:

  [InvalidArgumentException]
  Could not find a version of package drupal/media_entity_file_replace matching your minimum-stability (stable). Require it with an explicit version constraint allowing its desired stability.

Then specify the version:

composer require drupal/media_entity_file_replace:^1.0-beta3

To enable the module using Drush:

drush en media_entity_file_replace

2. Clear the cache. You can easily clear the cache via the Drupal admin UI at admin/config/development/performance or by the drush command:

drush cr

A quick overview of this step is adding a media field to an existing content type and uploading an actual media document. If you already have a media field in your content type and an uploaded media file then you can skip to step 3.

A. For any content type (we will use the default Drupal Article content type in this tutorial), add a Media field and check “Document” as the Reference type. See Image 1 below.
B. Go to Content >> Media and click on “Add Media”. At the next page, select “Document” and proceed to upload a file. Note the filename.

3. Now enable the “Replace file” widget that comes from the Media Entity File Replace module.

Go to Structure >> Media Types >> Document >> Manage Form Display and enable the “Replace file” widget. This widget is disabled by default. See Image 2 below. You will not be able to replace a file until you enable this widget.

It’s a good idea to position the “Replace file” widget right under the file widget as shown in Image 2 so that when a user is editing a file, the “Replace file” widget is right under the file that they want to replace.

Without this module and widget enabled, the default Drupal interface will appear as in Image 3.

4. Now if you go to Content >> Media and edit the document media that we uploaded in Step 2.B, you will see the “Replace file” widget as shown in Image 4 below. Notice that the default Drupal widget is automatically removed (see the difference between Image 3 and Image 4).

5. Go ahead and replace the original uploaded file with a new file with a different filename. Upon replacing the file, if you left the default option “Overwrite original file” checked, then Drupal will upload the new file and set the old file for deletion. Even if your new file has a new file name, Drupal will store the new file whilst retaining the filename of the original file. Note that the filename is the same as that noted from Step 2.B.

If you click on the new uploaded file even after doing a refresh in the browser, you may still see the old content of the original file. You must do a hard refresh in your browser to see the contents of the newly uploaded file.

More information: How to do a hard refresh in Chrome, Firefox and IE.

File Replace

This module allows editors to replace files at the file entity level by overwriting the existing files. Because it overwrites the files, the filename and path are exactly retained.

You should use this module if you want to allow content editors to replace file entities whilst keeping exactly the same filename and path as the original file. It is useful in cases where existing files in Drupal need to be updated occasionally.

Getting Started

1. Download and enable the module. This module requires no additional libraries and can simply be installed with composer which is the recommended way.

Using Composer:

composer require drupal/file_replace

To enable the module using Drush:

drush en file_replace

2. Clear the cache. You can easily clear the cache via the Drupal admin UI at admin/config/development/performance or by the drush command:

drush cr

3. There is one extra manual step that you must do. Because this module only provides the “Replace page” for each file upload, it does not provide a link to this page from the Drupal UI. You can access the “Replace page” directly by typing the URL into the browser. You can manually type the following URL into the browser:

admin/content/files/replace/{{ fid }}

Where {{ fid }} is the file id of the file you want to replace. For example, if the fid was 6, then you would go to:

admin/content/files/replace/6

This is not ideal. We will show you how to link to the page from the default Drupal Files overview page. (The outcome we are trying to achieve is shown in Image 11.)

Go to Content >> Files and click on “Edit view” as shown in Image 5.

Alternatively, you can go to Structure >> Views and edit the Files view as shown in Image 6.

4. Add a Custom text field to the Files View as shown in Image 7.

5. Then add some custom text for the text of the link. See Image 8

Also, edit the “Rewrite Results” section and enter the following in the “Link path”:

admin/content/files/replace/{{ fid }}

You can also enter custom text in the “Title text” field although this is just for aesthetic purposes. See Image 9 below.

Now click on “Apply (all displays)” and save your View.

6. The last step is to enable the “Replace files” permission for the role that you want. See Image 10.

7. Now go to the Files overview page at Content >> Files and you will see a “replace” link as shown in Image 11.

Click on the “replace” link next to the file you want to replace and this will take you to another page where you can upload a new file as shown in Image 12.

Common Pitfall – Caching

Static files served by Drupal are usually cached externally (outside of Drupal) by services such as Varnish, Content Delivery Network (CDN) and the user’s browser. By default, a user’s browser will not pick up the content of the newly uploaded file until after the max-age header which is set in .htaccess for two weeks for static files. In other words, if you replace a file and do nothing, end users will see the new file content after two weeks (unless they locally do a hard refresh).

Clearing Drupal’s internal cache will not solve this caching caveat because Drupal is not involved with serving static files. This is the job of your webserver.

There are a few options worth mentioning:

• Read the section on Caching on Media Entity File Replace module’s homepage (2 options are listed)
• After you replace a file, manually clear your Varnish/CDN/CloudFlare cache (not ideal but it works).
• Follow the discussion to integrate with the Purge module

Summary

Drupal does not retain filenames for uploaded files that are replaced or overwritten. Additionally, Drupal stores uploaded files as either media entities or file entities depending on your set up. This tutorial demonstrated how to retain existing file names when replacing media or file entities. There are two contributed modules you can use to solve this problem and they are Media Entity File Replace and File Replace. These modules will allow you to overwrite existing media and files respectively, whilst keeping their original filenames.