Black Magic Black Friday Sale! • Basic 10%, Advanced 25%, Pro 50% off • Coupon: BLACKMAGIC • Buy Now

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 321 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. 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.

      http://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,

  2. 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,

  3. 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,

  4. 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 Buchmann 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.

  5. 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 Buchmann 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.

  6. 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 *

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