Issues & FAQ

General Issues

Access Control (Roles)

By default, only the administror has access to the Renamer Dashboard, and any user with the manage_options role (typically, the administrator) has access to the settings.

You can override the access to the Dashboard by adding a filter on mfrh_allow_usage. The following snippet will allow editors to access it.

add_filter( 'mfrh_allow_usage', function( $allow ) {
  return current_user_can( 'editor' ) || $allow;
} );

If you are interested in overring who can access the settings, you can add a filter on mfrh_allow_setup, it works exactly the same way.

Customization

If you don’t know how to add custom code to WordPress, please check the artile about Add Custom PHP Code to WordPress.

Customize the filenames

We are all using different languages and our websites have different topics. Therefore, there are unlimited ways of automatically renaming filenames. Media File Renamer does it simply depending on the title you gave you the media. If you want to customize it, the best way is to implement this customization. You might need to be a developer to do this. The code below, for instance, will add “renamed-” in front of the filename proposed by the plugin. The $old filename is still accessible, and there is a reference to the attachment through the $post variable.

add_filter( 'mfrh_new_filename', 'my_filter_filename', 10, 3 );

function my_filter_filename( $new, $old, $post ) {
  return "renamed-" . $new;
}

Here is a more complex example, but also more interesting and useful. This one adds the upload date in front of the filename.

// Override the filename naming rules with this filter
add_filter( 'mfrh_new_filename', 'my_filter_filename', 10, 3 );

function my_filter_filename( $new, $old, $post ) {
  
  // Get the date from the $post (which is the media entry) and convert it to a timestamp
  $post_date = strtotime( $post['post_date'] );
  
  // Make this timestamp to looks like 2018-01-01
  $formatted_date = date('Y-m-d', $post_date);
  
  // Add this timestamp in front of the filename already decided by Media File Renamer
  $new_filename = $formatted_date . "-" . $new;
  
  return $new_filename;
}

If you own the Pro Version, there is an additional filter that works in a similar way, but has an additional parameter: the attached post. The filter is mfrh_new_filename_attached is you can use it this way:

// Override the filename naming rules with this filter
add_filter( 'mfrh_new_filename_attached', 'my_filter_filename', 10, 4 );

function my_filter_filename( $new, $old, $media, $attachedPost ) {
  $new_filename = $new .  '-' . sanitize_title( $attachedPost['post_title'] );
  return $new_filename;
}

Another filter allows you to do specify rules at the character level (but you can also specify whole strings).

add_filter( 'mfrh_replace_rules', 'replace_s_by_z', 10, 1 );

function replace_s_by_z( $rules ) {
  $rules['s'] = 'z';
  return $rules;
}

Customize the ALT texts

You should use the mfrh_rewrite_alt filter.

add_filter( 'mfrh_rewrite_alt', 'my_alt_filter', 10, 3 ); 

function my_alt_filter( $alt ) {   
  return $alt . ' ' . get_bloginfo( 'name' ); 
} 

Disable renaming based on rules

You can use the mfrh_allow_rename filter.

add_filter( 'mfrh_allow_rename', 'my_allow_rename_filter', 10, 2 ); 

function my_allow_rename_filter( $media, $manual_filename ) {   
  $id = $media['ID'];
  return true; 
} 

Automation

Trigger the renaming process

If you are using plugins or tools which generate the posts and/or upload the images automatically for you, then Media File Renamer might not be able to rename those files as they are not considered new uploads. You will need to find out how to hook into that process, and then trigger the Media File Renamer manually.

Best is to ask the developer of the plugin you are using to automate your WordPress for the best way how to do it. Once you know where to hook, you simply need to call this function available globally:

mfrh_rename( $mediaId ); 

Media File Renamer will rename this media entry depending on your settings. For your information, here are a few helpful action hooks in WordPress:

• publish_post: when a post is published
• post_updated: when a post is updated

Debug Issues

I am actively working on this page based on users’ request, issues, and questions. I am sorry if it seems a bit messy; I will make it clearer and better.

There are many themes and plugins available. Some of them manage images their own way, create their own metadata, hide important information in your database. Of course, Media File Renamer detects most of it and works perfectly on standard installs, but it can’t cover 100% of the WordPress installs, especially if they are a bit… exotic 🙂 In those cases, the reference to the file might not be renamed and appear broken.

Timeouts, Big Installs, Slow servers

If you have a big install and/or a slow server, then you might experience timeouts. The plugin runs 2 to 4 queries on your database. Those queries replace the old filenames by the new filenames.

Here are a few workarounds:

• Disable Updating References in the plugin’s options (if you don’t need those updates)
• Increase the time before it timeouts (Increase limits)
• Optimize the SQL queries specifically for your install (that should be done by a good developer around you); have a look at the action_update_posts and action_update_postmeta functions in the plugin
• Any other idea? Please let a comment 🙂

I have been thinking of an alternative that could work: making the renaming asynchronous and renaming the files in the posts, parsing them one by one. Of course, that would be a bad alternative for those with no such issues as the plugin would become slower. Unfortunately, there are no other alternatives. I don’t think it’s an issue in the long run, installs are getting better, and hosting services faster.

Have you moved your WordPress to a new hosting service?

This is a really annoying issue as it is very technical, and difficult to resolve. It also impacts your WordPress install dramatically, even though… at first, everything seems to work perfectly.

Impacted WordPress installs are the ones using a lot of UTF-8 files. It means they contain a lot of non-ASCII characters, such as commas, quotes, accents, special characters, etc. Many of my clients had issues related to that.

How to resolve it? It’s best to ask your hosting service. But here is a quick idea for you: remove all the content of your /uploads folder, and re-upload the content of this folder from your previous hosting service by FTP using an option that enforces the usage of UTF-8.

My site is (or my images are) broken, what can I do?

If the setting Update References is checked, the URLs used to reference your image in the content will be updated at every rename. However, even with this option enabled, some URLs might be skipped.

Before anything, check the next section about The Cache Issue.

First, use the Undo feature built in Media File Renamer to revert your latest renames. If that doesn’t help enough, you will unfortunately need to restore your site through your latest backup.

What does this happen? Because the URLs referencing your images is actually not really stored in the content; it might be somewhere else, in some hidden meta, and there are also a few page builders out there which encode all their content. That’s unfortunately impossible to update those references in those cases.

The best way is when the content references your images through their IDs, not their URLs. In that case, even if the filename changes (or anything else in fact, like the Title, ALT, etc), the output will be always exactly the one you expect.

If you would like to help me debug and potentially provide a solution, share with me (using screenshots) how your images are actually used by your WordPress (for example, in the page builder). That will be really helpful.

Please also have a look at your PHP Error Logs to rule out specific issues and errors.

Maybe it is not broken: The Cache Issue

WordPress installs are very cached nowadays. By plugins, by hosting services, CDN, etc. After renaming your files, you need to clear your cache. Not only your browser cache, but also your hosting service’s cache. And if you are using plugins to make your website faster, they will also have an option to reset your cache.

Sometimes the cache is cleared automatically, and you might know that. But for example, a plugin like WP Rocket (that does cache) doesn’t react when the meta for a post is updated, it does only clear its cache when the post itself is updated. So this is important: don’t believe the caching plugins are perfect, and clear your cache regularly.

Or else…

If you have a developer working for you, then he/she will be able to understand how your install work, and to teach Media File Renamer how to update the references, the way they are used by your install.

You can use the mfrh_url_renamed action (if you want to handle the new URL for this filename) or the mfrh_media_renamed action (if you want to handle the filename on your server) actions. Have a look at the examples in the plugins/custom.php file in the plugin directory.