---
title: How to Create a Custom File Renaming Rule
description: "Create a custom WordPress file renaming rule: add your own token to the filename structure and fill it with PHP."
url: "https://wpfactory.com/docs/create-custom-file-renaming-rule/"
updated: "2026-09-27"
category: Developers
---

# How to Create a Custom File Renaming Rule

[Rename Media Files: Improve Your WordPress SEO](https://wpfactory.com/item/file-renaming-on-upload-wordpress-plugin/) ships with a set of built-in rules, but you can also add your own token and fill it with any value you compute in PHP. This guide shows how to register a custom `{my_custom_rule}` token and, separately, how to ignore file extensions from code. Both approaches use filters, so add the snippets to your theme's `functions.php` or a small custom plugin.

### Step 1: Add your token to the Filename structure

Go to **WPFactory > File Renaming** in your WordPress admin. The settings page is titled **File Renaming on Upload** and is split into tabs. On the **General Settings** tab, add your token to the **Filename structure** field (`filename_structure`). For example:

```
{siteurl}{posttitle}{my_custom_rule}{filename}
```

A custom token only produces output once it is present in the Filename structure. The value comes from your filter in the next step, so the token does not need its own checkbox on the Rules tab.

### Step 2: Fill the token with the frou_sanitize_file_name filter

Use the `frou_sanitize_file_name` filter to set the translation for your token. In the example below the token resolves to the current user ID:

```
add_filter( 'frou_sanitize_file_name', function( $filename_infs ) {
    $filename_infs['structure']['translation']['my_custom_rule'] = get_current_user_id();
    return $filename_infs;
}, 20 );
```

Note that the array key (`my_custom_rule`) matches the token name without the braces. Return the full `$filename_infs` array so the rest of the renaming pipeline can run. Replace `get_current_user_id()` with whatever value you want to insert.

### Ignoring file extensions from code

If you want certain extensions left untouched during renaming, use the `frou_ignored_extensions` filter instead of listing them in the settings:

```
add_filter( 'frou_ignored_extensions', function ( $extensions ) {
    return array_merge( $extensions, array( 'txt', 'js', 'zip' ) );
} );
```

Files with those extensions keep their original names.

### Requirements

A custom token only takes effect when the **Filename structure** field includes it. If the token is missing from the structure, your filter value is never used. For the full list of available filters and actions, see the hooks and filters reference.

### Need a hand?

Our team answers every ticket on the [Rename Media Files support forum](https://wpfactory.com/support/item/file-renaming-on-upload-wordpress-plugin/).

Related articles

- [Understanding File Renaming Rules](https://wpfactory.com/docs/file-renaming-rule-guide/)
- [File Renaming Hooks and Filters Reference](https://wpfactory.com/docs/file-renaming-hooks-and-filters/)
- [How to Restrict File Renaming by User Role or Post Type](https://wpfactory.com/docs/restrict-file-renaming-by-user-role-or-post-type/)
- [How to Rename Files by Custom Field or Taxonomy](https://wpfactory.com/docs/rename-files-by-custom-field-or-taxonomy/)
- [File Renaming Settings Reference](https://wpfactory.com/docs/file-renaming-settings-reference/)