June 12, 2020: Improved support for non-latin characters.
Jun 27, 2018: Updated to use
get_upload_dir()method instead ofwp_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
| <?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 | |
| ) ); |
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:
- Include the name of the submitting user either before or after the file name.
- 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
- Check requirements
- Make sure you have Gravity Forms installed and activated.
- Already have a license? Download Latest Gravity Forms
- Need a license? Buy Gravity Forms
- Make sure you have Gravity Forms installed and activated.
- Install the snippet
- Copy and paste the entire snippet into your theme’s functions.php file.
- 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_idwith the ID of your form. - Replace the
field_idwith the field ID of your File Upload field. - Replace the
templatewith 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.
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.
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
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,
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
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.
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
Hi Chris,
This snippet supports GF Unique ID. Simply insert the merge tag for your Unique ID field in the
templateparameter.Instead of installing the snippet Network wide, I suggest using the Code Snippets plugin to manage the snippets on a per-site basis.
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
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,
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!
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,