Quick answer: WordPress already cleans many filenames during upload processing. In our Gravity Forms 3.1.3 staging test, common accents and spaces changed without custom code. Duplicate names received a numeric suffix, and some symbols were removed. You only need a custom rule when your workflow needs a stricter format, such as lowercase ASCII filenames.
This guide shows what happened in our real Gravity Forms File Upload field tests. It then adds a stricter WordPress filename filter and compares the results. Your results can vary with WordPress, Gravity Forms, other plugins, and server settings.
Need Gravity Forms? Get Gravity Forms and use its File Upload field for the examples in this tutorial.
Key Takeaways
- WordPress already provides core filename sanitization, including accent handling, whitespace cleanup, and special-character rules.
- A custom sanitize_file_name filter can enforce lowercase ASCII filenames, but the filter is global and is not limited to Gravity Forms.
- Our strict rule made filenames more predictable, but it also replaced a fully Japanese basename with uploaded-file.
- Filename cleanup is not the same as file validation, malware scanning, access control, or secure storage.
- Test the rule on staging before production, including uploads, exports, and any automation that depends on filenames.
How Does WordPress Sanitize Uploaded Filenames?
Direct answer: WordPress has a core sanitize_file_name() function. It calls remove_accents() first, also removes a defined set of special characters and normalizes whitespace to dashes. It trims certain punctuation at the start and end and has special handling for filenames with multiple extensions.
After the core function finishes, WordPress exposes the sanitize_file_name filter. That is the filter used later in this tutorial. In our Gravity Forms staging test, the filter changed the stored upload filename as expected.
Gravity Forms also has its own File Upload settings for file size and allowed extensions. Those settings solve a different problem. They control what can be uploaded, while filename sanitization controls how the name is cleaned.
What Gravity Forms Did With Uploaded Filenames by Default
Test setup: Gravity Forms 3.1.3, one single File Upload field, no custom filename filter, tested on staging on October 6, 2026.
We uploaded seven filename patterns to see what was saved in the Gravity Forms entry. These are observed test results, not assumptions.
| Original filename | Saved filename | What we observed |
|---|---|---|
| Résumé été.txt | Resume-ete.txt | Common Latin accents removed; spaces became hyphens. |
| My File With Spaces.txt | My-File-With-Spaces.txt | Spaces became hyphens. |
| price-€-£-$-100.txt | price-£-100.txt | Symbols did not all behave the same in this test. |
| report.final.version.txt | report.final_.version.txt | The multi-dot name was changed. |
| UPPERCASE.TXT | UPPERCASE.TXT | Uppercase name and extension stayed uppercase. |
| duplicate.txt, uploaded twice | duplicate.txt, then duplicate1.txt | The second file received a numeric suffix. |
| 日本語ファイル.txt | 日本語ファイル.txt | The Japanese basename was preserved. |
The main lesson is simple: do not add custom code just to remove common accents or spaces until you test the native result first.
When Do You Need Stricter Filename Sanitization?
Direct answer: Use a stricter rule only when the default filename format does not meet a real workflow requirement.
A stricter filename can help when another system expects simple lowercase ASCII names. It can also help when scripts rely on a predictable pattern or a team wants one format across uploads. This can matter when files move through Gravity Forms integrations, APIs, storage systems, or automation tools.
It can also help on public forms that collect files such as logos or documents. For example, our public submission business directory tutorial uses a Gravity Forms File Upload field for business logos.
Do not use ASCII-only cleanup by default on a multilingual site. A strict rule can remove meaningful text from filenames written in Japanese, Arabic, Chinese, Greek, and other scripts.
Add a Strict Filename Policy in WordPress
| Scope warning: The sanitize_file_name filter is a WordPress-wide filter. It can affect filenames processed outside this one Gravity Forms field. Test media uploads, Gravity Forms uploads, and export workflows on staging before you use it in production. |
Gravity Forms has documented cases where a poorly designed sanitize_file_name filter can interfere with CSV exports. See the official Gravity Forms export troubleshooting guide. Our snippet does not use the problematic random-name pattern described there, but the global scope is still a reason to test carefully.
Add the code with a code snippets plugin or a small site-specific plugin. This keeps the rule separate from your theme.
add_filter( 'sanitize_file_name', function ( $filename, $filename_raw ) {
$extension = pathinfo( $filename, PATHINFO_EXTENSION );
$basename = pathinfo( $filename, PATHINFO_FILENAME );
// Lowercase the filename.
$basename = strtolower( $basename );
// Keep only ASCII letters and numbers.
// Replace every other group of characters with one hyphen.
$basename = preg_replace( '/[^a-z0-9]+/', '-', $basename );
$basename = trim( $basename, '-' );
// Avoid an empty basename for filenames made only from
// characters outside this strict ASCII policy.
if ( $basename === '' ) {
$basename = 'uploaded-file';
}
$extension = strtolower( $extension );
return $extension !== ''
? $basename . '.' . $extension
: $basename;
}, 20, 2 );This rule works on the filename WordPress has already processed. It lowercases the basename and extension. It keeps only the letters a-z and numbers 0-9 in the basename. Other character groups become one hyphen. It uses uploaded-file if the basename becomes empty.
The second callback argument, $filename_raw, is the original filename supplied to the WordPress hook. This snippet accepts it to match the hook signature, but it does not need the raw value for this strict policy.
What Changed With the Strict Filename Policy?
We kept the same Gravity Forms test form and enabled the strict filter. The table below compares the native result with the strict result.
| Original filename | Native result | Strict result |
|---|---|---|
| UPPERCASE.TXT | UPPERCASE.TXT | uppercase.txt |
| Résumé été.txt | Resume-ete.txt | resume-ete.txt |
| My File With Spaces.txt | My-File-With-Spaces.txt | my-file-with-spaces.txt |
| price-€-£-$-100.txt | price-£-100.txt | price-e-100.txt |
| report.final.version.txt | report.final_.version.txt | report-final-version.txt |
| repeat-test.txt, uploaded twice | Not used in native set | repeat-test.txt, then repeat-test1.txt |
| 日本語ファイル.txt | 日本語ファイル.txt | uploaded-file.txt |
The strict policy made the output more predictable. It also changed more than the native flow. That extra cleanup is useful only if your workflow actually needs it.
Does WordPress Remove Accents From Filenames?
Yes, for many common accented characters. WordPress calls remove_accents() inside its filename sanitization function. The exact replacements are defined by WordPress and some depend on locale.
In our native Gravity Forms test, Résumé été.txt became Resume-ete.txt. The strict filter then lowercased that result to resume-ete.txt. This means the custom regex was not needed just to remove those accents.
How Does WordPress Handle Spaces and Special Characters in Filenames?
Spaces are normally normalized, but special characters do not all have one universal outcome. The official sanitize_file_name() documentation lists characters that WordPress removes and explains how whitespace is converted to dashes.
Our test showed why it is better to verify than to guess. My File With Spaces.txt became My-File-With-Spaces.txt. The symbol test price-€-£-$-100.txt became price-£-100.txt in the native Gravity Forms test and price-e-100.txt with the strict filter.
WordPress also has special logic for multiple extensions. Intermediate extension-like parts can receive an underscore when they are not in the allowed extension list. That helps explain why report.final.version.txt became report.final_.version.txt in our native test.
Can You Make Uploaded Filenames Lowercase in WordPress?
Yes. The strict filter above lowercases both the basename and the extension. In our native test, UPPERCASE.TXT stayed uppercase. With the filter active, it became uppercase.txt.
Lowercase names can make automation rules and naming conventions easier to manage. They are not required for every WordPress or Gravity Forms site.
Should You Remove Non-Latin Characters From Filenames?
Only if your destination requires ASCII-only filenames. The strict regex in this tutorial allows only a-z and 0-9 in the basename. That means a filename written entirely in another script can lose its original text.
Our Japanese test showed the trade-off clearly. Native handling preserved 日本語ファイル.txt. The strict policy converted it to uploaded-file.txt because the basename had no ASCII letters or numbers left after the regex.
For multilingual sites, native Unicode filenames may be the better choice. Do not call the ASCII-only result “cleaner” unless compatibility with another system is the actual requirement.
Filename Sanitization Is Not File Upload Security
A clean filename does not prove that a file is safe. Filename sanitization only changes the name. It does not replace file-type checks, allowed-extension rules, malware controls, access control, or storage policy.
Gravity Forms can restrict allowed extensions and maximum file size in the File Upload field settings. Its documentation also explains that uploaded file URLs are obscured but are not access-controlled by default. If uploaded documents are sensitive, review the official File Upload Security guide before launch.
How to Remove or Roll Back the Custom Filename Policy
To roll back, disable the snippet or remove the filter from your site-specific plugin. Future filenames will then follow WordPress core and any other active filters.
Files that were already uploaded are not automatically renamed back. If an existing file must be renamed, treat that as a separate migration task. Test any saved links or integrations that depend on the old name.
Using Gravity Forms With Sanitized Uploaded Files
In our working strict-filter tests, Gravity Forms still saved a file link in the entry. The duplicate test also kept working: the first repeat-test.txt stayed as-is and the second became repeat-test1.txt. We did not add custom duplicate logic.
If you include file-upload links in reports, exports, or other downstream processes, retest those workflows after any global filename rule. Our Gravity Forms Entries in Excel tutorial is one example of a workflow where file-upload links can be part of exported entry data.
Want to build the form used in this type of workflow? Get Gravity Forms (affiliate link).
Final Takeaway
WordPress already does more filename cleanup than many sites need. In our Gravity Forms tests, common accents and spaces were handled without custom code. A stricter sanitize_file_name rule is useful when a real system requires lowercase ASCII names. It has a cost: non-Latin filenames can lose their meaning.
Test the native behavior first. Add stricter rules only when the workflow needs them. Then test the full path from upload to entry, export, automation, and storage.
For more practical guides, browse the GravityWP tutorial library.
Frequently Asked Questions
In our staging test, a WordPress sanitize_file_name filter changed filenames submitted through a Gravity Forms File Upload field. This confirms the filter is part of the upload path we tested.
WordPress removes a defined set of special characters and normalizes whitespace, but different characters can produce different results. Test the filenames that matter to your workflow.
WordPress uses remove_accents() during sanitize_file_name(). In our test, “Résumé été.txt” became “Resume-ete.txt” without custom filename code.
Yes. A sanitize_file_name filter can lowercase the basename and extension. The snippet in this tutorial did that in our Gravity Forms test.
No. Filename cleanup is separate from file-type validation, malware controls, access control, and secure storage.
Our Premium add-ons for Gravity Forms
List Datepicker
Add a Datepicker with calendar select to a column or multiple columns in a Gravity Forms List Field.
n8n Connector
Connect Gravity Forms to n8n and automate your workflows with secure, flexible, and powerful webhooks. Go beyond simple notifications and build advanced, two-way automations.
List Number Format
With this Gravity Forms Add-on you can change List Field columns into a number field, do calculations within a row or column. Extra merge tags are available with total counts of columns.
Field to Entries
Create entries based on Checkboxes & Multi Select choices & List Field rows.
Read tutorials about
How to Validate Repeatable Contact Rows in Gravity Forms
Learn how to validate repeatable Gravity Forms List field rows with GravityWP List Text. This tutorial shows how to add email and regex validation, test invalid values, and confirm that valid team roster data is stored correctly.
Gravity Forms Airtable Integration: Create Records From Form Submissions
Learn how to build a Gravity Forms Airtable integration with GravityWP API Connector. Send form submissions to Airtable, create new records automatically, and save the returned Airtable Record ID and response back to Gravity Forms.
Gravity Forms Asana Integration: Create Tasks From Form Submissions
Learn how to connect Gravity Forms to Asana with GravityWP API Connector. This tested workflow creates Asana tasks from form submissions and saves the returned task ID and URL back to Gravity Forms.
Gravity Forms Google Calendar Integration: Create Events From Form Submissions
Connect Gravity Forms to Google Calendar with GravityWP API Connector. Learn how to create calendar events from form submissions, map event details, configure OAuth 2.0, handle time zones, and save the returned Event ID and URL.
