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 302 Comments

  • 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
Show CodeDownload Code
<?php
/**
* Gravity Wiz // Gravity Forms // Rename Uploaded Files
*
* Rename uploaded files for Gravity Forms. You can create a static naming template or using merge tags to base names on user input.
*
* Features:
* + supports single and multi-file upload fields
* + flexible naming template with support for static and dynamic values via GF merge tags
*
* Uses:
* + add a prefix or suffix to file uploads
* + include identifying submitted data in the file name like the user's first and last name
*
* @version 2.4
* @author David Smith <david@gravitywiz.com>
* @license GPL-2.0+
* @link http://gravitywiz.com/rename-uploaded-files-for-gravity-form/
*/
class GW_Rename_Uploaded_Files {
public function __construct( $args = array() ) {
// set our default arguments, parse against the provided arguments, and store for use throughout the class
$this->_args = wp_parse_args( $args, array(
'form_id' => false,
'field_id' => false,
'template' => ''
) );
// do version check in the init to make sure if GF is going to be loaded, it is already loaded
add_action( 'init', array( $this, 'init' ) );
}
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_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 );
}
function rename_uploaded_files( $entry, $form ) {
if( ! $this->is_applicable_form( $form ) ) {
return $entry;
}
foreach( $form['fields'] as &$field ) {
if( ! $this->is_applicable_field( $field ) ) {
continue;
}
$uploaded_files = rgar( $entry, $field->id );
if( empty( $uploaded_files ) ) {
continue;
}
$uploaded_files = $this->parse_files( $uploaded_files, $field );
$stashed_files = $this->parse_files( gform_get_meta( $entry['id'], 'gprf_stashed_files' ), $field );
$renamed_files = array();
foreach( $uploaded_files as $_file ) {
// Don't rename the same files twice.
if( in_array( $_file, $stashed_files ) ) {
$renamed_files[] = $_file;
continue;
}
$dir = wp_upload_dir();
$dir = $this->get_upload_dir( $form['id'] );
$file = str_replace( $dir['url'], $dir['path'], $_file );
if( ! file_exists( $file ) ) {
continue;
}
$renamed_file = $this->rename_file( $file, $entry );
if ( ! is_dir( dirname( $renamed_file ) ) ) {
wp_mkdir_p( dirname( $renamed_file ) );
}
$result = rename( $file, $renamed_file );
$renamed_files[] = $this->get_url_by_path( $renamed_file, $form['id'] );
}
// In cases where 3rd party add-ons offload the image to a remote location, no images can be renamed.
if( empty( $renamed_files ) ) {
continue;
}
if( $field->get_input_type() == 'post_image' ) {
$value = str_replace( $uploaded_files[0], $renamed_files[0], rgar( $entry, $field->id ) );
} else if( $field->multipleFiles ) {
$value = json_encode( $renamed_files );
} else {
$value = $renamed_files[0];
}
GFAPI::update_entry_field( $entry['id'], $field->id, $value );
$entry[ $field->id ] = $value;
}
return $entry;
}
function get_upload_dir( $form_id ) {
$dir = GFFormsModel::get_file_upload_path( $form_id, 'PLACEHOLDER' );
$dir['path'] = dirname( $dir['path'] );
$dir['url'] = dirname( $dir['url'] );
return $dir;
}
function rename_uploaded_files_after_update( $form, $entry_id ) {
$entry = GFAPI::get_entry( $entry_id );
$this->rename_uploaded_files( $entry, $form );
}
/**
* Stash the "final" version of the files after other add-ons have had a chance to interact with them.
*
* @param $entry
* @param $form
*/
function stash_uploaded_files( $entry, $form ) {
foreach ( $form['fields'] as &$field ) {
if ( ! $this->is_applicable_field( $field ) ) {
continue;
}
$uploaded_files = rgar( $entry, $field->id );
gform_update_meta( $entry['id'], 'gprf_stashed_files', $uploaded_files );
}
return $entry;
}
function stash_uploaded_files_after_update( $form, $entry_id ) {
$entry = GFAPI::get_entry( $entry_id );
$this->stash_uploaded_files( $entry, $form );
}
function rename_file( $file, $entry ) {
$new_file = $this->get_template_value( $this->_args['template'], $file, $entry );
$new_file = $this->increment_file( $new_file );
return $new_file;
}
function increment_file( $file ) {
$file_path = GFFormsModel::get_physical_file_path( $file );
$pathinfo = pathinfo( $file_path );
$counter = 1;
// increment the filename if it already exists (i.e. balloons.jpg, balloons1.jpg, balloons2.jpg)
while ( file_exists( $file_path ) ) {
$file_path = str_replace( ".{$pathinfo['extension']}", "{$counter}.{$pathinfo['extension']}", GFFormsModel::get_physical_file_path( $file ) );
$counter++;
}
$file = str_replace( basename( $file ), basename( $file_path ), $file );
return $file;
}
function is_path( $filename ) {
return strpos( $filename, '/' ) !== false;
}
function get_template_value( $template, $file, $entry ) {
$info = pathinfo( $file );
if( strpos( $template, '/' ) === 0 ) {
$dir = wp_upload_dir();
$template = $dir['basedir'] . $template;
} else {
$template = $info['dirname'] . '/' . $template;
}
// replace our custom "{filename}" psuedo-merge-tag
$value = str_replace( '{filename}', $info['filename'], $template );
// replace merge tags
$form = GFAPI::get_form( $entry['form_id'] );
$value = GFCommon::replace_variables( $value, $form, $entry, false, true, false, 'text' );
// make sure filename is "clean"
$filename = $this->clean( basename( $value ) );
$value = str_replace( basename( $value ), $filename, $value );
// append our file ext
$value .= '.' . $info['extension'];
return $value;
}
function is_applicable_form( $form ) {
$form_id = isset( $form['id'] ) ? $form['id'] : $form;
return $form_id == $this->_args['form_id'];
}
function is_applicable_field( $field ) {
$is_file_upload_field = in_array( GFFormsModel::get_input_type( $field ), array( 'fileupload', 'post_image' ) );
$is_applicable_field_id = $this->_args['field_id'] ? $field['id'] == $this->_args['field_id'] : true;
return $is_file_upload_field && $is_applicable_field_id;
}
function clean( $str ) {
return sanitize_file_name( $str );
}
function get_url_by_path( $file, $form_id ) {
$dir = $this->get_upload_dir( $form_id );
$url = str_replace( $dir['path'], $dir['url'], $file );
return $url;
}
function parse_files( $files, $field ) {
if( empty( $files ) ) {
return array();
}
if( $field->get_input_type() == 'post_image' ) {
$file_bits = explode( '|:|', $files );
$files = array( $file_bits[0] );
} else if( $field->multipleFiles ) {
$files = json_decode( $files );
} else {
$files = array( $files );
}
return $files;
}
}
# Configuration
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
) );
view raw gw-gravity-forms-rename-uploaded-files.php hosted with ❤ by GitHub

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.

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 31+ essential add-ons for Gravity Forms with support you can count on.

Comments

  1. Danny says

    Hi, I found if field value (merge tag) is Chinese string, the final filename will display alphabet instead Chinese. How could I resolve this?

    Reply

    • Ryan Donovan says

      Hello Danny, This is an interesting question. What language is your website currently set to within the WordPress/Database settings? Let us know.😃

    • Danny says

      Hi Ryan, my WordPress website language is set to Traditional Chinese, MySQL Database is set to UTF-8 Unicode (utf8mb4).

      If the field value is “一二三” ( it means 123 in Chinese), then final filename will display “yyy”. If there is 3 Chinese words, it will become 3 y.

    • Ryan Donovan says

      Hello Ivan, Could you elaborate on your use case? That would help to see if we have a solution for this. Thank you!

  3. Chad Smith says

    Holy *&**$$@ !!!! –

    Thank you so much for adding this snippet. It is such a timesaver! We rely heavily on GF for some of our inventory duties and you just saved us literally hundreds of hours per year.

    Thank you sincerely for your time and willingness to share this AMAZING bit of code.

    A Million Thanks. Take Care.

    Reply

  4. Kenny says

    Hi David… I’m pretty new to GF and I added your file upload renaming code & works like a champ.. (Thank you!!) However, when it comes to Multiple Instances, Same Form – (2 different file uploads / same form) where am I adding the code you supplied for the class snippet?? I assumed I would add it in functions.php where the original renaming config code was, but that errored out. Any advice or instructions would be greatly appreciated! Thanks!!

    Reply

  6. Kris Lippi says

    I have a photo upload form where I direct people to name the photos in the order they want them displayed, ex: 1.jpg, 2.jpg etc.

    By default, multiple uploads of 1.jpg and 2.jpg etc will be renamed 11.jpg, 21.jpg etc.

    I thought I could use this function with the Gravity Wiz Unique ID add on to uniquely name the files as 00011-1.jpg etc, but it still adds on numbers to the filename on submission.

    Is there a way to use this function to keep the order without adding on an additional number for duplicate file names?

    Reply

    • David Smith says

      Hi Kris, this should work but I believe there are still files in the folder with the original 1.jpg, 2.jpg, etc names. If you remove those original files, this should work moving forward.

    • Kris Lippi says

      Hi David – thanks for the reply. I’m trying to use this solution to uniquely rename uploaded files because users will upload files with the same name. So user1 could upload photo1.jpg and user2 could also upload photo1.jpg.

      I was hoping to use this function with GW’s unique id to rename them but it looks like it renames them but after the default rename that happens when multiple files get uploaded with the same name. So I lose the original name. Does that make sense?

    • David Smith says

      Hi Gary, I’m not sure. Likely not without customization/extension of the snippet. I’d check with the developer and see if he is storing the order ID in the entry meta.

  11. Tim says

    what if I have a form field for a stock number “SU438125” and from that stock number I upload 8 vehicle photos and I want them to be renamed: SU438125_1.jpg SU438125_2.jpg SU438125_3.jpg SU438125_4.jpg SU438125_5.jpg SU438125_6.jpg SU438125_7.jpg SU438125_8.jpg

    is this possible?

    Reply

    • David Smith says

      Hi Tim, it should auto-enumerate the filenames. The tricky part will be getting the “1” on the first one…

  12. Tobias says

    This is great! Is it possible to tweak the snippet so it also work with recordings uploaded with the Gravity forms Pipe addon?

    Reply

    • David Smith says

      We haven’t tested this scenario but we’re happy to add it as a feature request.

  13. Sean P Sullivan says

    I asked this before with no reply, but has anyone noticed that GF 2.4.8 or better breaks this function. I have the latest code installed. The files do upload to proper folder but do not rename. Help!

    Reply

    • Sean Sullivan says

      Well, turns out that GF version was not the issue but rather WP 5.*. I have a function that allows me to specify the upload folder by form id. So when the rename function tried to do it’s thing it was getting all confused because it tried to use the default upload path. Because of this, you can’t use the GFFormsModel::get_physical_file_path function. It actually did nothing due to the incorrect path vs url problem.

      Took me a long time to debug it…but finally did. I fixed it by creating my own $this->_get_physical_file_path function:

      http://snippi.com/s/uu1ctgf

      I then replaced calls to the GFFormsModel one in the rename_uploaded_files function and it all started working again.:)

      http://snippi.com/s/fzxwoko

    • David Smith says

      Hi Sean, this is still working for me with the latest version of Gravity Forms.

    • Sean P Sullivan says

      Issue is that somewhere along the way over the last few month something changed that is causing the rename functions to not recognized the true upload path and is defaulting. I fixed the code, see my previous reply.

  14. Adam Reynolds says

    This is great, but any chance you could extend this functionality so that it applies to any form and/or any form upload fields, so that I can add, say, a timestamp to the end of each file upload, or a random number, etc.?

    Thanks, Adam

    Reply

    • Adam Reynolds says

      No, unfortunately, that doesn’t work. Execution stops at is_applicable_form (line 54) and returns an uninitialized $entry. Any idea how this could be adapted to apply to all forms and upload fields?

    • Thad Winzenz says

      @Antoone – we’ve needed the admin label (value) for one of our forms as well. We have competitors uploading an .mp3 file to use as part of a performance and need those files renamed to match the division and name of the competitor.

      Here’s what works for us to populate the admin value instead of the field label for the ‘Division’ component of the naming.

      ‘template’ => ‘{Division:2:value}-{Name (First):3.3}-{Name (Last):3.6}’

      Essentially, put :value trailing the field reference.

  15. Michael Cornelius says

    Hi I was redirected here from GF. My question relates to a file upload from the front end when and used by non-technical staff. I have a member of staff who generates a pdf file containing the latest information, they will then upload to wp, and when the page is next called in wp it uses the latest pdf file. The issue I have is that when GF uploads the file because one already exists by that name a suffix is added to the file being uploaded, which of course means the wp page does not open the new file. GF suggest that this snippit might do the trick. I’m already a GW client using the Populate Anywhere perp. Thanks Michael

    Reply

    • David Smith says

      Hi Michael, it sounds like what you want to do is overwrite the previously uploaded file with the new file? Is that correct? If so, this snippet will not be much help as it would still append the suffix as to not overwrite the existing file.

    • Michael Cornelius says

      Hi Dave

      Yes that is correct. Do you know of such a solution please, I thought it would have been a common need but have carried out a number of googles without success – but being a newbie to WP et al I might be asking the wrong question. Thanks Michael

  16. Antoine says

    Thanks, that’s great !

    I’m currently hacking this code to run it for any form that have one or more upload fields. Therefore I modified is_applicable_form & is_applicable_field functions : http://snippi.com/s/9w1f0jc (note : with these hacks, form_id and field_id parameters won’t be used anymore) Seems to work as a POC, but maybe you’d like to refine/correct it ?

    What I’d like also is to set the template parameter so that the field name is added among – say- last name field and original filename. Can I use a “merge tag” like in parameters array or should I hack later, while in the loop ?

    Reply

    • David Smith says

      Hi Antoine, first, I’d recommend extending the class rather than modifying it. This way you can overwrite the functions you want and still replace the base class with newer versions as they become available. Here’s an example:

      http://snippi.com/s/c7wnilw

      I’m not sure I understand what you’re trying to do with the field name and template parameter?

    • Antoine says

      Hi David, thank you for these helpful comments. Still a bit fresh on php/wp but I’ll certainly extend V.S modify the code.

      What we might have on a single form is multiple upload fields for different usages, say a personal photo and an ID scan. We’d like to be able to identify each like : [form field name]-{firstname}-{lastname}-{filename}.

      Also, I noticed that my hack has a flaw; the form will be submitted (and confirmation sent) as many times as there are upload fields in the form. Sure have to add some controls to prevent this … any idea ?

    • Antoine says

      HI David, as mentioned above, I’m facing a problem I cannot solve by myself. If my form contains more than one fileupload field, everything seems to be ok but the confirmation message is sent as many times than there are fields.

      I’ve been trying several combinations, hooking on gform_disable_notification filter with no luck, I’m probably missing something obvious here …

      Basically, what I do is : 1. In the parameters array, I’ve added a “field_nb” parameter (defaulted to 0) 2. In the “is_applicable_form” function, while looping into the fields to find (eventually) fileupload file types, I increment this parameter so that we know how many fields should be treated before sending notification. 3. I tried various combinations I’m to shameful to share here (hooking on gform_disable_notification) with no luck … Basically I just wanted to switch notification for this particular entry off by default and reactivate it (in the ‘foreach’ fields loop) only for the last field. I guess I’ve reached my limit here … help very welcome :)

    • Antoine says

      David, I’m really sorry for flooding (and my poor English). This will meant more than my words : http://snippi.com/s/darpu4y

      1. Done in the stash_uploaded_files function
      2. Attempt to use WP apply_filter function

      State : I can disable notification, can’t enable it back …

  19. Zachariah says

    This is working great. Just one question to see if this is possible. Would it be possible to change the file name AND convert to uppercase in the process? I have a field in GF that I’ve converted to uppercase before saving in the db. This field is also being used to create a query string that gets passed to the form where the file upload and renaming happens. This query string doesn’t use the uppercase value saved in the database but rather whatever the user put in.

    Thanks!

    Reply

    • David Smith says

      Hi Zachariah, your best bet is to modify the clean() method to also uppercase the string.

Leave a Reply

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

This site uses Akismet to reduce spam. Learn how your comment data is processed.