`GF_Field_FileUpload`

Source: includes/fields/class-gf-field-fileupload.php:8

Details

Kind: class
Namespace: (global)
Extends: GF_Field

Properties

Property	Type	Description
`$forms_upload_roots`	`string[]`	Stores the upload root dir for forms.
`$forms_default_upload_roots`	`string[]`	Stores the default upload root dir for forms.

Methods

Method	Description
`get_file_upload_path_info()`	Gets the file upload path information including the actual saved physical path from the entry meta if found.
`get_default_upload_roots()`	Gets the default upload roots using the form ID and current time.
`get_upload_root_info()`	Returns the default file upload root and url for files stored by the provided form.
`get_form_editor_field_description()`	Returns the field's form editor description.
`get_form_editor_field_icon()`	Returns the field's form editor icon.
`get_form_editor_field_settings()`	Returns the class names of the settings which should be available on the field in the form editor.
`is_check_type_and_ext_disabled()`	Determines if the file type and extension check should be disabled.
`get_max_file_size_bytes()`	Returns the maximum file size in bytes.
`get_clean_allowed_extensions()`	Returns an array of cleaned allowed extensions.
`get_size_validation_message()`	Returns the file size validation message.
`is_invalid_file()`	Validates the given file.
`validate()`	Validates the field value(s).
`get_field_input()`	Returns the field inner markup.
`is_value_empty()`	Is the given value considered empty for this field.
`is_value_submission_empty()`	Used to determine the required validation result.
`unset_uploaded_file()`	Remove invalid file from the uploaded files array.
`get_value_save_input()`	Returns the value to be saved to the entry.
`get_multifile_value()`	Gets the JSON encoded array of file URLs to be saved for the multifile enabled field.
`check_existing_entry()`	Check existing entry for the file to re-use its URL rather than recreating as the date may be different.
`get_parsed_list_of_files()`	Given the comma-delimited string of file paths, get the JSON array representing
`get_single_file_value()`	Gets the value to be saved for the single file input.
`get_value_entry_detail()`	Format the entry value for display on the entry detail page and for the {all_fields} merge tag.
`get_value_merge_tag()`	Gets merge tag values.
`get_download_url()`	Returns the download URL for a file. The URL is not escaped for output.
`get_extra_entry_metadata()`	Stores the physical file paths as extra entry meta data.
`get_file_upload_path_meta_key_hash()`	Gets a hash of the file URL to be used as the meta key when saving the file physical path to the entry meta.
`get_submission_files()`	Returns an array of files found in the submission for the current field.
`set_submission_files()`	Caches the submission files in a context property and the existing files in GFFormsModel::$uploaded_files.
`is_submission_files_empty()`	Determines if the submission files array is empty.
`get_submission_files_for_preview()`	Normalizes the submission files array, including the uploaded_filename for new files, so it can be used to generate the preview markup.
`get_tmp_file_details_from_submission_files()`	Returns the file details from the existing submission files.
`get_new_file_from_submission_files()`	Returns the file parsed from $_FILES by $this->get_submission_files() that matches the given name.
`get_tmp_file_details()`	Returns the temporary file details.
`upload_submission_tmp_files()`	Returns an array of temporary files uploaded to the form tmp folder for the current submission.
`upload_tmp_file()`	Moves the file from the PHP tmp folder to the form tmp folder.
`get_input_value_submission()`	Supports using the dynamic population feature to populate the field on initial form display with file URLs.
`populate_file_urls_from_value()`	Triggers population of GFFormsModel::$uploaded_files with any file URLs found in the given value.
`populate_file_url()`	Populates the submission_files context property & GFFormsModel::$uploaded_files with the details array for the given file URL.
`get_file_name_from_url()`	Parses the file name/basename from the given URL.

Method Reference

`get_file_upload_path_info()`

public static function get_file_upload_path_info( $file_url, $entry_id=null )

Gets the file upload path information including the actual saved physical path from the entry meta if found.

Parameters

Name	Type	Default	Description
`$file_url`	`string`		The file URL to look for.
`$entry_id`	`integer` \| `null`	`null`	The entry ID.

Returns

array

Since: 2.5.16

Source: includes/fields/class-gf-field-fileupload.php:40

`get_default_upload_roots()`

public static function get_default_upload_roots( $form_id )

Gets the default upload roots using the form ID and current time.

Parameters

Name	Type	Default	Description
`$form_id`	`int`		The form ID to create the root for,

Returns

string[] — The root path and url.

Since: 2.5.16

Source: includes/fields/class-gf-field-fileupload.php:63

`get_upload_root_info()`

public static function get_upload_root_info( $form_id )

Returns the default file upload root and url for files stored by the provided form.

Parameters

Name	Type	Default	Description
`$form_id`	`integer`		The form ID of the form that will be used to generate the directory name.

Returns

array

Since: 2.5.16

Source: includes/fields/class-gf-field-fileupload.php:96

`get_form_editor_field_description()`

public function get_form_editor_field_description()

Returns the field's form editor description.

Returns

string

Since: 2.5

Source: includes/fields/class-gf-field-fileupload.php:119

`get_form_editor_field_icon()`

public function get_form_editor_field_icon()

Returns the field's form editor icon.

This could be an icon url or a gform-icon class.

Returns

string

Since: 2.5

Source: includes/fields/class-gf-field-fileupload.php:132

`get_form_editor_field_settings()`

public function get_form_editor_field_settings()

Returns the class names of the settings which should be available on the field in the form editor.

Returns

string[]

Since:

1.9
2.9.18 (Updated to include the dynamic population setting.)

Source: includes/fields/class-gf-field-fileupload.php:144

`is_check_type_and_ext_disabled()`

public function is_check_type_and_ext_disabled()

Determines if the file type and extension check should be disabled.

Returns

bool

Since: 2.9.18

Source: includes/fields/class-gf-field-fileupload.php:169

`get_max_file_size_bytes()`

public function get_max_file_size_bytes()

Returns the maximum file size in bytes.

Returns

int

Since: 2.9.18

Source: includes/fields/class-gf-field-fileupload.php:191

`get_clean_allowed_extensions()`

public function get_clean_allowed_extensions()

Returns an array of cleaned allowed extensions.

Returns

array

Since: 2.9.18

Source: includes/fields/class-gf-field-fileupload.php:208

`get_size_validation_message()`

public function get_size_validation_message()

Returns the file size validation message.

Returns

string

Since: 2.9.18

Source: includes/fields/class-gf-field-fileupload.php:225

`is_invalid_file()`

public function is_invalid_file( $file, $is_new=true )

Validates the given file.

Parameters

Name	Type	Default	Description
`$file`	`array`		The file to validate.
`$is_new`	`bool`	`true`	Whether the file is new (from $_FILES) or an existing file (from GFFormsModel::$uploaded_files).

Returns

array | false — Returns an array containing the sanitized file name and validation message when invalid, or false when valid.

Since: 2.9.18

Source: includes/fields/class-gf-field-fileupload.php:283

`validate()`

public function validate( $value, $form )

Validates the field value(s).

Parameters

Name	Type	Default	Description
`$value`	`string`		Empty or the JSON encoded array of files for an existing entry.
`$form`	`array`		The form being processed.

Returns

void

Since:

1.9
2.9.18 (Updated to use $this->get_submission_files() & $this->is_valid_file().)

Source: includes/fields/class-gf-field-fileupload.php:365

`get_field_input()`

public function get_field_input( $form, $value='', $entry=null )

Returns the field inner markup.

Parameters

Name	Type	Default	Description
`$form`	`array`		The Form Object currently being processed.
`$value`	`string` \| `array`	`''`	The field value. From default/dynamic population, $_POST, or a resumed incomplete submission.
`$entry`	`null` \| `array`	`null`	Null or the Entry Object currently being edited.

Returns

string

Since:

1.9
2.9.18 (Updated to use $this->get_clean_allowed_extensions(), $this->get_max_file_size_bytes(), and $this->get_submission_files_for_preview().)

Source: includes/fields/class-gf-field-fileupload.php:444

`is_value_empty()`

public function is_value_empty( $value )

Is the given value considered empty for this field.

Parameters

Name	Type	Default	Description
`$value`	`string` \| `array`		The value to check.

Returns

bool

Since: 2.9.18

Source: includes/fields/class-gf-field-fileupload.php:694

`is_value_submission_empty()`

public function is_value_submission_empty( $form_id )

Used to determine the required validation result.

Parameters

Name	Type	Default	Description
`$form_id`	`int`		The ID of the form currently being processed.

Returns

bool

Since:

1.9
2.7.1 (Updated to validate multifile uploads exist in the tmp folder.)
2.7.4 (Added the gform_validate_required_file_exists filter.)
2.9.2 (Updated to use GFFormsModel::get_tmp_upload_location().)
2.9.18 (Updated to use $this->get_submission_files().)

Source: includes/fields/class-gf-field-fileupload.php:711

`unset_uploaded_file()`

public function unset_uploaded_file( $input_name, $key )

Remove invalid file from the uploaded files array.

Parameters

Name	Type	Default	Description
`$input_name`
`$key`

Returns

void

Since: 2.7.4

Deprecated: 2.9.18

Source: includes/fields/class-gf-field-fileupload.php:788

`get_value_save_input()`

public function get_value_save_input( $value, $form, $input_name, $entry_id, $entry, $repeater_index='' )

Returns the value to be saved to the entry.

Parameters

Name	Type	Default	Description
`$value`	`string`		The value to be saved.
`$form`	`array`		The form currently being processed.
`$input_name`	`string`		The input name used when accessing the $_POST.
`$entry_id`	`int`		The ID of the entry currently being saved.
`$entry`	`array`		The entry properties and values that have already been saved for the current submission.
`$repeater_index`	`string`	`''`	The repeater index if the field is inside a repeater.

Returns

string — The sanitized and formatted input value to be saved.

Since:

1.9
2.9.18 (Updated to cache the entry and form in context properties.)
3.0.0 (Renamed to get_value_save_input)

Source: includes/fields/class-gf-field-fileupload.php:809

`get_multifile_value()`

public function get_multifile_value( $form_id, $input_name, $value, $entry_id=null )

Gets the JSON encoded array of file URLs to be saved for the multifile enabled field.

Parameters

Name	Type	Default	Description
`$form_id`	`int`		ID of the form.
`$input_name`	`string`		Name of the input (e.g. input_1).
`$value`	`string`		Value of the input.
`$entry_id`	`int`	`null`	ID of the entry.

Returns

string

Since:

1.9
2.6.8 (Added $entry_id parameter.)
2.9.18 (Updated to use $this->get_submission_files() and $this->filter_submission_files_pre_save().)

Source: includes/fields/class-gf-field-fileupload.php:841

`check_existing_entry()`

public function check_existing_entry( $entry_id, $input_name, $file_info )

Check existing entry for the file to re-use its URL rather than recreating as the date may be different.

Parameters

Name	Type	Description
`$entry_id`	`int`	The id of the current entry
`$input_name`	`string`	The name of the input field (input_1)
`$file_info`	`array`	Array of file details

Returns

mixed — Array of file details or URL of existing file

Since:

2.6.8
2.9.18 (Updated to support dynamically populated file URLs.)

Source: includes/fields/class-gf-field-fileupload.php:953

`get_parsed_list_of_files()`

public function get_parsed_list_of_files( $value, $form_id=0, $input_name='' )

Given the comma-delimited string of file paths, get the JSON array representing

any which still exist (i.e., haven't been deleted using the UI).

Parameters

Name	Type	Default	Description
`$value`	`string`		A comma-delimited list of file paths.
`$form_id`	`int`	`0`	The form ID for this entry.
`$input_name`	`string`	`''`	The input name holding the current list of files.

Returns

false | string

Since:

2.5.8
2.9.18 (Updated to use $this->get_submission_files() and deprecated the $form_id and $input_name params.)

Source: includes/fields/class-gf-field-fileupload.php:1002

`get_single_file_value()`

public function get_single_file_value( $form_id, $input_name )

Gets the value to be saved for the single file input.

Parameters

Name	Type	Default	Description
`$form_id`	`int`		ID of the form.
`$input_name`	`string`		Name of the input (e.g. input_1).

Returns

string

Since:

1.9
2.9.18 (Updated to use $this->get_submission_files(), $this->filter_submission_files_pre_save(), & GFFormsModel::get_tmp_upload_location().)

Source: includes/fields/class-gf-field-fileupload.php:1036

`get_value_entry_detail()`

public function get_value_entry_detail( $value, $currency='', $use_text=false, $format='html', $media='screen' )

Format the entry value for display on the entry detail page and for the {all_fields} merge tag.

Parameters

Name	Type	Default	Description
`$value`	`string` \| `array`		The field value.
`$currency`	`string`	`''`	The entry currency code.
`$use_text`	`bool` \| `false`	`false`	When processing choice based fields should the choice text be returned instead of the value.
`$format`	`string`	`'html'`	The format requested for the location the merge is being used. Possible values: html, text, or url.
`$media`	`string`	`'screen'`	The location where the value will be displayed. Possible values: screen or email.

Returns

string | false

Since: 2.9.18 (Updated to use $this->get_file_name_from_url().)

Source: includes/fields/class-gf-field-fileupload.php:1178

`get_value_merge_tag()`

public function get_value_merge_tag( $value, $input_id, $entry, $form, $modifier, $raw_value, $url_encode, $esc_html, $format, $nl2br )

Gets merge tag values.

Parameters

Name	Type	Description
`$value`	`array` \| `string`	The value of the input.
`$input_id`	`string`	The input ID to use.
`$entry`	`array`	The Entry Object.
`$form`	`array`	The Form Object
`$modifier`	`string`	The modifier passed.
`$raw_value`	`array` \| `string`	The raw value of the input.
`$url_encode`	`bool`	If the result should be URL encoded.
`$esc_html`	`bool`	If the HTML should be escaped.
`$format`	`string`	The format that the value should be.
`$nl2br`	`bool`	If the nl2br function should be used.

Returns

string — The processed merge tag.

Since: Unknown

Source: includes/fields/class-gf-field-fileupload.php:1263

`get_download_url()`

public function get_download_url( $file, $force_download=false )

Returns the download URL for a file. The URL is not escaped for output.

Parameters

Name	Type	Default	Description
`$file`	`string`		The complete file URL.
`$force_download`	`bool`	`false`	If the download should be forced. Defaults to false.

Returns

string

Since: 2.0

Source: includes/fields/class-gf-field-fileupload.php:1367

`get_extra_entry_metadata()`

public function get_extra_entry_metadata( $form, $entry )

Stores the physical file paths as extra entry meta data.

Parameters

Name	Type	Default	Description
`$form`	`array`		The form object being saved.
`$entry`	`array`		The entry object being saved.

Returns

array — The array that contains the file URLs and their corresponding physical paths.

Since: 2.5.16

Source: includes/fields/class-gf-field-fileupload.php:1445

`get_file_upload_path_meta_key_hash()`

public static function get_file_upload_path_meta_key_hash( $file_url )

Gets a hash of the file URL to be used as the meta key when saving the file physical path to the entry meta.

Parameters

Name	Type	Default	Description
`$file_url`	`string`		The file URL to generate the hash for.

Returns

string

Since: 2.5.16

Source: includes/fields/class-gf-field-fileupload.php:1511

`get_submission_files()`

public function get_submission_files()

Returns an array of files found in the submission for the current field.

Returns

array[] — {

Since: 2.9.18

Source: includes/fields/class-gf-field-fileupload.php:1540

`set_submission_files()`

public function set_submission_files( $files )

Caches the submission files in a context property and the existing files in GFFormsModel::$uploaded_files.

Parameters

Name	Type	Default	Description
`$files`	`null` \| `array[]`		Null to flush the submission_files property or the array to be cached. See get_submission_files() for format.

Returns

void

Since: 2.9.18

Source: includes/fields/class-gf-field-fileupload.php:1603

`is_submission_files_empty()`

public function is_submission_files_empty( $files=null )

Determines if the submission files array is empty.

Parameters

Name	Type	Default	Description
`$files`	`null` \| `array[]`	`null`	See get_submission_files().

Returns

bool

Since: 2.9.18

Source: includes/fields/class-gf-field-fileupload.php:1663

`get_submission_files_for_preview()`

public function get_submission_files_for_preview()

Normalizes the submission files array, including the uploaded_filename for new files, so it can be used to generate the preview markup.

Returns

array[]

Since: 2.9.18

Source: includes/fields/class-gf-field-fileupload.php:1678

`get_tmp_file_details_from_submission_files()`

public function get_tmp_file_details_from_submission_files( $name )

Returns the file details from the existing submission files.

Parameters

Name	Type	Default	Description
`$name`	`string`		The original file name.

Returns

array

Since: 2.9.18

Source: includes/fields/class-gf-field-fileupload.php:1713

`get_new_file_from_submission_files()`

public function get_new_file_from_submission_files( $name )

Returns the file parsed from $_FILES by $this->get_submission_files() that matches the given name.

Parameters

Name	Type	Default	Description
`$name`	`string`		The original file name.

Returns

array

Since: 2.9.18

Source: includes/fields/class-gf-field-fileupload.php:1739

`get_tmp_file_details()`

public function get_tmp_file_details( $file_or_name )

Returns the temporary file details.

Parameters

Name	Type	Default	Description
`$file_or_name`	`array` \| `string`		A file from $this->get_submission_files() or $_FILES, or a filename.

Returns

array — {

Since: 2.9.18

Source: includes/fields/class-gf-field-fileupload.php:1767

`upload_submission_tmp_files()`

public function upload_submission_tmp_files()

Returns an array of temporary files uploaded to the form tmp folder for the current submission.

Returns

array[]

Since: 2.9.18

Source: includes/fields/class-gf-field-fileupload.php:1816

`upload_tmp_file()`

public function upload_tmp_file( $file )

Moves the file from the PHP tmp folder to the form tmp folder.

Parameters

Name	Type	Default	Description
`$file`	`array`		The file details parsed by $this->get_submission_files() from $_FILES.

Returns

array — The temporary file details.

Since: 2.9.18

Source: includes/fields/class-gf-field-fileupload.php:1904

`get_input_value_submission()`

public function get_input_value_submission( $standard_name, $custom_name='', $field_values=[], $get_from_post_global_var=true )

Supports using the dynamic population feature to populate the field on initial form display with file URLs.

Parameters

Name	Type	Default	Description
`$standard_name`	`string`		The input name used when accessing the $_POST.
`$custom_name`	`string`	`''`	The dynamic population parameter name.
`$field_values`	`array`	`[]`	The dynamic population parameter names with their corresponding values to be populated.
`$get_from_post_global_var`	`bool`	`true`	Whether to get the value from the $_POST array as opposed to $field_values.

Returns

array | string | null

Since: 2.9.18

Source: includes/fields/class-gf-field-fileupload.php:1950

`populate_file_urls_from_value()`

public function populate_file_urls_from_value( $value )

Triggers population of GFFormsModel::$uploaded_files with any file URLs found in the given value.

Parameters

Name	Type	Default	Description
`$value`	`string` \| `array`		A single file URL, a comma-seperated list of file URLs, a JSON encoded array of file URLs, or an array of file URLs.

Returns

void

Since: 2.9.18

Source: includes/fields/class-gf-field-fileupload.php:1978

`populate_file_url()`

public function populate_file_url( $url )

Populates the submission_files context property & GFFormsModel::$uploaded_files with the details array for the given file URL.

Parameters

Name	Type	Default	Description
`$url`	`string`		The file URL.

Returns

false | array — {

Since: 2.9.18

Source: includes/fields/class-gf-field-fileupload.php:2016

`get_file_name_from_url()`

public function get_file_name_from_url( $url )

Parses the file name/basename from the given URL.

Parameters

Name	Type	Default	Description
`$url`	`string`		The file URL.

Returns

false | array — {

Since: 2.9.18

Source: includes/fields/class-gf-field-fileupload.php:2083

Details
Properties
Methods
Method Reference

Details​

Properties​

Methods​

Method Reference​

get_file_upload_path_info()​

Parameters​

Returns​

get_default_upload_roots()​

Parameters​

Returns​

get_upload_root_info()​

Parameters​

Returns​

get_form_editor_field_description()​

Returns​

get_form_editor_field_icon()​

Returns​

get_form_editor_field_settings()​

Returns​

is_check_type_and_ext_disabled()​

Returns​

get_max_file_size_bytes()​

Returns​

get_clean_allowed_extensions()​

Returns​

get_size_validation_message()​

Returns​

is_invalid_file()​

Parameters​

Returns​

validate()​

Parameters​

Returns​

get_field_input()​

Parameters​

Returns​

is_value_empty()​

Parameters​

Returns​

is_value_submission_empty()​

Parameters​

Returns​

unset_uploaded_file()​

Parameters​

Returns​

get_value_save_input()​

Parameters​

Returns​

get_multifile_value()​

Parameters​

Returns​

check_existing_entry()​

Parameters​

Returns​

get_parsed_list_of_files()​

Parameters​

Returns​

get_single_file_value()​

Parameters​

Returns​

get_value_entry_detail()​

Parameters​

Returns​

get_value_merge_tag()​

Parameters​

Returns​

get_download_url()​

Parameters​

Returns​

get_extra_entry_metadata()​

Parameters​

Returns​

get_file_upload_path_meta_key_hash()​

Parameters​

Returns​

get_submission_files()​

Returns​

set_submission_files()​

Parameters​

Returns​

Details

Properties

Methods

Method Reference

`get_file_upload_path_info()`

Parameters

Returns

`get_default_upload_roots()`

Parameters

Returns

`get_upload_root_info()`

Parameters

Returns

`get_form_editor_field_description()`

Returns

`get_form_editor_field_icon()`

Returns

`get_form_editor_field_settings()`

Returns

`is_check_type_and_ext_disabled()`

Returns

`get_max_file_size_bytes()`

Returns

`get_clean_allowed_extensions()`

Returns

`get_size_validation_message()`

Returns

`is_invalid_file()`

Parameters

Returns

`validate()`

Parameters

Returns

`get_field_input()`

Parameters

Returns

`is_value_empty()`

Parameters

Returns

`is_value_submission_empty()`

Parameters

Returns

`unset_uploaded_file()`

Parameters

Returns

`get_value_save_input()`

Parameters

Returns

`get_multifile_value()`

Parameters

Returns

`check_existing_entry()`

Parameters

Returns

`get_parsed_list_of_files()`

Parameters

Returns

`get_single_file_value()`

Parameters

Returns

`get_value_entry_detail()`

Parameters

Returns

`get_value_merge_tag()`

Parameters

Returns

`get_download_url()`

Parameters

Returns

`get_extra_entry_metadata()`

Parameters

Returns

`get_file_upload_path_meta_key_hash()`

Parameters

Returns

`get_submission_files()`

Returns

`set_submission_files()`

Parameters

Returns