Gravity Wiz

Magically enhanced tutorials, snippets and plugins for Gravity Forms!

Rename Uploaded Files For Gravity Forms

Rename uploaded files for Gravity Forms. You can create a static naming template or using merge tags to base names on user input.

Last updated | Written by 394 Comments

  • March 23, 2022: Fixed issue where editing entries belonging to forms with multiple GW_Rename_Uploaded_Files on the same form would cause files to be re-renamed.

  • March 12, 2021: Added ignore_extension option.

  • June 12, 2020: Improved support for non-latin characters.

  • Jun 27, 2018: Updated to use get_upload_dir() method instead of wp_upload_dir().

  • November 19th, 2016: Fixed typo in method name.

  • October 24, 2016: Fixed issue with Gravity Forms 2.0.7. Major refactor. Requires Gravity Forms 2.0.7.15 or greater.

  • December 5, 2015: Added support for Post Image fields.

  • September 22, 2015: Updated to remove forward and backslashes from new filename.

  • March 26, 2015: Fixed issue when submitting form with no uploaded files

Show All Updates
View CodeDownload Code

Stop! There's a better way.

This snippet is available as a plugin with Gravity Perks, a suite of over 47 premium Gravity Forms plugins!

We wrote a snippet that will allow you to create a dynamic naming template for your uploaded Gravity Form files. This includes the ability to prepend, append or generate from scratch custom file names. You can use merge tags to include user input in your new file names.

Here are a couple use cases where this snippet might be useful:

  1. Include the name of the submitting user either before or after the file name.
  2. Include an event name in the file name to better categorize which files belong to which events.

For example, given an original file name of mountains.png and a template of {Name (First):1.3}-{Name (Last):1.6}-{filename}, the final image name would be Jordan-Smith-mountains.png

Getting Started

  1. Check requirements
  2. Install the snippet
    • Copy and paste the entire snippet into your theme’s functions.php file.
  3. Configure the snippet
    • Once you have installed the snippet, find the snippet configuration section located at the bottom of the snippet code.
    • Replace the form_id with the ID of your form.
    • Replace the field_id with the field ID of your File Upload field.
    • Replace the template with your custom file name template.

Usage Examples

First and Last Name

new GW_Rename_Uploaded_Files( array(
	'form_id'  => 628,
	'field_id' => 3,
	'template' => '{Name (First):1.3}-{Name (Last):1.6}-{filename}', // most merge tags are supported, original file extension is preserved
) );

In this example, we are prepending the first and last name from the form to easily identify who submitted the file. Most merge tags are supported using this method and the original file extension is preserved.

Form Title Merge Tag

new GW_Rename_Uploaded_Files( array(
	'form_id'  => 12,
	'field_id' => 18,
	'template' => '{form_title}-{filename}', // most merge tags are supported, original file extension is preserved
) );

In this example, we are prepending the title of the form to the filename to quickly identify which form the file was uploaded to.

Static Text

new GW_Rename_Uploaded_Files( array(
	'form_id'  => 628,
	'field_id' => 5,
	'template' => 'static-file-name',
) );

You can use any text you’d like, just make sure to add the {filename} merge tag somewhere in there.

Ignore Extension

new GW_Rename_Uploaded_Files( array(
	'form_id'          => 628,
	'field_id'         => 5,
	'template'         => 'static-file-name',
	'ignore_extension' => true,
) );

By default, this snippet takes the extension into consideration when renaming files. For example, static-file-name.jpg is different from static-file-name.png. You can change this behavior to ignore the extension of a file so in this scenario static-file-name.png would be renamed to static-file-name1.png as there’s already a static-file-name file uploaded.

Parameters

  • form_id (integer) (required)

    Your Form ID. There is no default value.

  • field_id (integer) (required)

    The Field ID of the file upload field. There is no default value.

  • template (string or merge tag) (required)

    This is the template that controls how the file will be rewritten. The value can be either a static string or a merge-tag(s). There is no default value.

You never need to include the file extension in your template. It will automatically be included.

Was this helpful?

We hope you find this snippet useful! If you do, show us some love by sharing this article on the social media platform of your choice. Let’s keep the Gravity Wiz pumping out awesome snippets. Thanks!

Did this resource help you do something awesome with Gravity Forms?

Then you'll absolutely love Gravity Perks; a suite of 47+ essential add-ons for Gravity Forms with support you can count on.

Comments

  1. Patrick says

    Hello!

    Nice option. I want added :ymd to the date into the code. But is it true that this is not supported? It’s looks like this: {Expiry date:39:ymd}

    Thank you.

    Reply

    • Samuel Bassah says

      Hi Patrick,

      That wouldn’t work. The output format for a Date field’s merge tag is set by the Date Format option in the field settings. Change this to yyy-mm-dd and the file will be renamed accordingly. You can’t also have slashes in the file name so this format, yyyy/mm/dd, won’t work.

      Best.

    • Samuel Bassah says

      Hi Shak,

      That is the configuration for the snippet. You’re to replace or update the value for the template key with the name you want to use to rename the file. If you’ll be getting the name from another field on the form, then you’ll update the ID of the merge tags accordingly.

      I hope this helps.

      Best,

  3. Chris Gillispie says

    Hi. Can I use this snippet to prepend a merge tag, such as username for a logged in user, to the original filename? I need to retain the original filename.

    Thanks

    Reply

    • Samuel Bassah says

      Hi Chris,

      This should be possible if you populate the username into a field on the form. You can then use a configuration like what’s below to prepend the Username to the filename.

      new GW_Rename_Uploaded_Files( array( 'form_id' => 628, 'field_id' => 3, 'template' => '{Username:10}{filename}', ) );

  5. Alphan Nguyen says

    Hi, I have 3 upload fields in 1 forms and want to rename each files with format: file1-001, file2-002, file3-003 . Could the snippet do that? and how to modify the snippet?

    Reply

    • Samuel Bassah says

      Hi Alphan,

      This should be possible with the snippet. You’ll create three copies of the snippet configuration, and set them up to target each of the file upload fields. Here is documentation on how to apply a snippet to more than one field.

      Best,

    • Tim Bare says

      Hey, Scott – Yes, I’m using the latest version of the snippet.

      Additional info that may be useful – the redirected folder is not in web root — it’s confidential data, so we’re auto-saving it to an external mount — /share (as an example) — I’ve also removed the URL in the upload path redirect code as there won’t be a path that’s accessible from the dashboard or email.

      Hope that helps clarify.

    • David Smith says

      Hey Tim, responded to your ticket but sharing here for other folks. Setting the url via the gform_upload_path resolved this issue for me.

      add_filter( 'gform_upload_path', 'change_upload_path', 10, 2 );
function change_upload_path( $path_info, $form_id ) {
    $path_info['path'] = '/Users/David/Local Sites/local/_test';
    $path_info['url'] = admin_url();
    return $path_info;
}

    • CakePlease says

      Where is the filter for the gform_upload_path supposed to go, to make this work right? I have a multi-form field on my form (set with max 1 upload). The filter currently is place in the init() function like this, but it does not work for me

      public function init() {

    // make sure we're running the required minimum version of Gravity Forms
    if ( ! is_callable( array( 'GFFormsModel', 'get_physical_file_path' ) ) ) {
        return;
    }

        add_filter("gform_upload_path", "change_upload_path", 10, 2);
    add_filter( 'gform_entry_post_save', array( $this, 'rename_uploaded_files' ), 9, 2 );
    add_filter( 'gform_entry_post_save', array( $this, 'stash_uploaded_files' ), 99, 2 );

    add_action( 'gform_after_update_entry', array( $this, 'rename_uploaded_files_after_update' ), 9, 2 );
    add_action( 'gform_after_update_entry', array( $this, 'stash_uploaded_files_after_update' ), 99, 2 );
}

    • Samuel Bassah says

      Hi,

      I’m guessing the filter snippet stands on its own. You can use the snippet David shared above without adding it to the Rename Uploaded files snippet. However, if you want to customize the Rename Uploaded files snippet with this filter, then we’ll need to forward this to our developers. If you have an active Gravity Perks Pro license you get in touch with us via our support form so our developers can take a look at your request.

      Best,

    • CakePlease says

      Thanks Samuel, it does work when placed outside of the class. Dont know why i was trying to over complicate things.

  7. Austin DuBois says

    Hello! Can you give the front end user to rename their files as they see them on the uploads? While using Uploads Pro, you can see the previews of each image, as they load, along with the file name. It would be great to be able to have a pencil icon next to the file name, to be able to quickly rename that file. Can you help?

    Reply

    • Samuel Bassah says

      Hi Austin,

      This is currently not supported and we don’t have a snippet for this. I will forward this to our developers as a feature request.

      Best,

  8. Schalk says

    Hi, This is great, thank you!

    Is it possible to change a merge field to lowercase when assigning the template? something like this:

    ‘template’ => strtolower(‘{:3}’),

    Also, when an image with the same name is uploaded, a number are automatically added. is it possible to add a – before the number so it reads image-1.jpg and not image1.jpg

    Reply

    • Samuel Bassah says

      Hi Schalk,

      Changing the merge field to lowercase wouldn’t work like that. The template parameter expects a static value or a merge tag. You’ll have to change the field value to lowercase after submission but before the entry is created so that the merge tag picks up the lowercase value.

      To add a dash when there is an image with the same name, you’ll have to customize the snippet. If you have an active Gravity Perks License, you can get in touch with us via our support form, so our developers can take a look into this.

      Best,

  9. Matt Jackman says

    Thank you GW team! I kept getting issues with similar filenames being uploaded into S3 and getting unpredictable filenames for referencing. This has cleaned that up for me…much appreciated.

    Reply

  11. Ken Kramer says

    Hi Everyone,

    I am trying to get the date to appear in the name of the my uploaded file, I tried using the merge tag of {Date:3}, {Date:3.1} (and .2 / .3) and {Date:3:value}, I am not wanting the date to appear as a date of 2/8/2021, but 2021-02-08 would be perfect, this way my client can see images in date order for example.

    Any thoughts?

    Thanks!

    Ken

    Reply

  12. Melvin says

    Very useful code!

    Is it possible to strip out special characters from the merge tags? I have a PHP function that does that, but can I insert PHP that calls a function inside your code snippet or will it break it?

    BTW I got 3 gravity perks last week, the nested forms rock!

    Reply

    • David Smith says

      What you can do is extend our class with your own and then modify the clean function to do any kind of sanitization you want.

      class Your_Rename_Uploaded_Files extends GW_Rename_Uploaded_Files { function clean( $str ) { return $str; } }

  13. Ben says

    Thanks for this code – it’s been really useful!

    I’ve been having an issue recently where a small number of files renamed using this snippet end up being saved as zero bytes in size.

    There’s no obvious pattern to the affected files themselves, and in some cases the issue affects only a subset of files uploaded along with a single form submission.

    I see no errors in the Apache or PHP logs that could shed light on the problem, and I haven’t been able to reproduce the problem myself. My best guess right now is that renaming is sometimes kicking in before the file uploads have finished, perhaps due to load on the server – is that a possibility?

    If so, is there any way to ensure the uploads are definitely complete before renaming triggers? (Even just a way to ensure the original file isn’t lost would be helpful; I can’t find them in GF’s temporary upload folder.) And if not, can you think of any other explanations?

    Thanks,

    Reply

    • Samuel Bassah says

      Hi Ben,

      I haven’t experienced such before so I’m guessing this is an issue related to your server. You may want to check out our GP Media Library Perk, which enables the feature to automatically import uploaded files to the WordPress Media Library when the form is submitted. This can help ensure that you don’t lose any uploaded files in case you don’t find them in the GF Temporary upload folder.

      Best,

  15. Stephan Verduyn says

    Hi,

    When I’m pasting this snippet into my functions.php file I’m getting an error:

    “There has been a critical error on your website. Please check your site admin email inbox for instructions.

    Learn more about debugging in WordPress.”

    how come? Do I need to change something more else than the bottom part?

    Kind regards, Vincent

    Reply

    • Samuel Bassah says

      Hi Stephan,

      It sounds like you might be having some trouble with installing the snippet. Please refer to our article on snippet troubleshooting for details on installing our snippets.

      https://gravitywiz.com/documentation/snippet-troubleshooting/

      However, if you’re a Gravity Perks Subscriber and you still experience issues installing the snippet, you can send us a message via our support form so we can take a closer look into it.

      I hope this helps.

      Best,

    • Stephan Verduyn says

      Hi Samuel,

      Got it, thanks. And if you want to rename the file to a field other then the name? How could u achieve this?

      Kind regards,

    • Samuel Bassah says

      Hi Stephan,

      Set the template parameter to the merge tag of the field you want to use its value to rename the file 'template' => '{:23}'

      Best,

  16. Albert Bretado says

    Like one of the replies above, I have multi site, so I cant add the code above to my functions as it will interfere with other GF’s. I tried using code snippet plugin but it throws an error. Do you have any other suggestion? On the functions file, Is there a way to check for site ID and then apply the code?

    Reply

    • Samuel Bassah says

      Hi Albert,

      You can get the Current site/blog ID with this get_current_blog_id();, you can then put the snippet configuration inside an if statement to check if the current site id is equal to the ID of the site you want to target. Something like this should work for you.

      if (get_current_blog_id() == 4 ){ new GW_Rename_Uploaded_Files( array( 'form_id' => 628, 'field_id' => 3, 'template' => '{Name (First):1.3}-{Name (Last):1.6}-{filename}' ) ); }

      I hope this helps.

      Best,

  17. Stuart says

    Thanks for the clear instructions. It’s works on one image. In my form I have more than one image to be renamed. Do I need to use the whole code snippet each time for a new FieldID in the same form? Example Form ID is the same, Field ID changes, and naming works as your above instructions.

    In fact, I’d like to use the snippet once and the rename instruction multiple times and for different forms. Is this possible? Then I just concentrate the renaming functionality in one place.

    Thanks

    Reply

    • Samuel Bassah says

      Hi Stuart,

      If you want to use the file rename snippet on more than one file upload field, you can create multiple copies of just the configuration. You don’t have to duplicate the entire snippet, but just the configuration part which will create multiple instances of the Class. Here is an article on how to apply a class-based snippet multiple times.

      Best,

  18. Chelsea says

    I have 4 file upload fields per form entry. Each of these 4 upload fields are multi upload.

    I would want file name to be “Postage[EntryID]X” Where entry ID is the form entry ID and X is the upload number, so first upload is 1, then 2 etc.

    How do I go about that (a bit confused because I have multi-upload and multiple fields? Thanks

    Reply

    • Scott Ryer says

      Hi Chelsea,

      You can use the {entry_id} merge tag to insert the entry ID into the renamed file, however numbering the files inside a multi-upload field isn’t currently supported.

      What you could do instead is use GF Nested Forms with a Single File upload field inside the Nested Form. You could then use the :count merge tag modifier in a field in the Nested Form to count the number of uploaded files, as shown in this article.

  19. Chris says

    I have a WP Multisite set up with http://www.mainsite.com/subsite/... format. I have plugins for Gravity Forms and Wp DataTables with Gravity Forms integration. I also have the Gravity Perks installed. My sub-sites are designed for separate use/access by separate clients. The sub-sites each have a number of Gravity Forms that are ‘checklists’ collecting info on different things. A number of the forms are checklists for reviewing documents and they have a file upload field to enable the client to upload a pdf copy of the document that they reviewed.

    Can this snippet be applied to work on a Multi-site set up for a number of different forms each with a file upload field?

    On each form I use the GF Perks Unique ID to create a unique sequential number for each submitted form. Is it possible for the upload file to be include this in the new file name?

    For example a file to be renamed as “XX00123Company Name” where XX00123 is the Unique ID sequential number and Company Name is the value input for a given company name field in the form.

    As I say I will have another separate form for, say, a legal document checklist with another Unique ID, say. “LG001” and, say, a document title name field, say, “Trust Deed” that I would want the file upload to be saves as “LG001_Trust Deed” .

    As I am using WP Multisite I can See Gravity is already storing the upload files in the gravity form folders under separate site number folders. I would however like to avoid it creating its subfolders for Year and Month of submission. ( I know there is another snippet for defining the path which I ope to use for this)

    How can I apply your snippet on Multisite and for different forms? Am I right in thinking the functions.PHP sits at Network level so I think I need the snippet to take account of the site number to ensure the files are save in the folders for each site?

    I would be grateful for your advice

    Reply

    • Scott Ryer says

      Hi Chris,

      This snippet supports GF Unique ID. Simply insert the merge tag for your Unique ID field in the template parameter.

      Instead of installing the snippet Network wide, I suggest using the Code Snippets plugin to manage the snippets on a per-site basis.

  20. matt says

    Amazing bit of code, its helping me out massively. THANK YOU!

    I have a question, is it possible to pass a user input on the form into the filename?

    For example, user enters an order number and uploads a file, the filename includes the order number?

    Kind Regards

    Reply

    • Samuel Bassah says

      Hi Matt,

      Most Merge tags are supported, so this should be possible if you update the template parameter in the configuration with the merge tag of the Order Number field. Something like this should get it working

      'template' => '{OrderNumber:113}-{filename}'

      Best,

    • Matt says

      Thanks Samuel,

      Can you quickly confirm the following, in the string: {OrderNumber:113}-{filename}

      What does the “:113” refer to? Is it the form field ID?

      Kind Regards

      Matt PS. many thanks for a super quick response on the last thread!

    • Samuel Bassah says

      Hi Matt,

      113 is the Field ID for the Order Number field. You may want to check out this documentation to get a better understanding of merge tags.

      Best,

Leave a Reply

Your email address will not be published. Required fields are marked *

By commenting, I understand that I may receive emails related to Gravity Wiz and can unsubscribe at any time.

Download Snippet

Rename Uploaded Files For Gravity Forms

This field is for validation purposes and should be left unchanged.