gform_submission_files_pre_save_field_value

Description

gform_submission_files_pre_save_field_value allows filtering (e.g., renaming) of the submission files before they are saved to the form uploads folder and entry.

Usage

add_filter( 'gform_submission_files_pre_save_field_value', 'my_function', 10, 4 );

Parameters

ParameterTypeDescription
$filesarrayArray of submission files. See Files Parameters.
$fieldGF_Field_FileUploadThe File Upload field the files are for.
$entryarrayThe entry currently being saved. Only fields located before the current field are included.
$formarrayThe form currently being processed.

Files Parameters

ParameterTypeDescription
newarrayArray of new files from $_FILES. See New File Parameters.
existingarrayArray of dynamically populated file URLs and/or files that have already been uploaded to the form tmp folder. See Existing File Parameters.

New File Parameters

ParameterTypeDescription
namestringThe original name of the file on the client machine.
typestringThe MIME type of the file provided by the browser.
sizeintegerThe size of the file in bytes.
tmp_namestringThe temporary filename of the file in which the uploaded file was stored on the server.
errorintegerThe PHP error code for the file upload.
full_pathstringThe full path as submitted by the browser. Only populated with PHP 8.1+.

Existing File Parameters

ParameterTypeDescription
uploaded_filenamestringThe name of the uploaded file, an existing file, or the name parsed from the populated URL.
temp_filenamestring|nullThe temporary name of the file. Only present if the file has been saved to the form tmp folder.
urlstring|nullThe file URL. Only present if the file has been dynamically populated on initial form display.

Examples

Rename uploaded files to include the entry and field IDs.

add_filter( 'gform_submission_files_pre_save_field_value', function ( $files, $field, $entry ) {
    $entry_id = absint( rgar( $entry, 'id' ) );

    foreach ( $files['existing'] as &$existing_file ) {
        $existing_file['uploaded_filename'] = sprintf(
            'entry-%d-field-%d-%s',
            $entry_id,
            $field->id,
            $existing_file['uploaded_filename']
        );
    }

    foreach ( $files['new'] as &$new_file ) {
        $new_file['name'] = sprintf(
            'entry-%d-field-%d-%s',
            $entry_id,
            $field->id,
            $new_file['name']
        );
    }

    return $files;
}, 10, 3 );

Placement

This code can be used in the functions.php file of the active theme, a custom functions plugin, a custom add-on, or with a code snippets plugin.

See also the PHP section in this article: Where Do I Put This Code?

Source Code

The filter is located in GF_Field_FileUpload::filter_submission_files_pre_save() in includes/fields/class-gf-field-fileupload.php

Since

Gravity Forms 2.9.18