Validating Form Submissions with the GFAPI

Introduction

The GFAPI::validate_form() method, added in Gravity Forms 2.6.3.2, is used to validate the form input values.

If the form passes validation the configured anti-spam checks will also be performed.

The following features and processes are NOT supported:

  • Saving progress for the save and continue feature
  • Payment add-on validation
  • Saving the entry
  • Add-on feeds
  • Notifications
  • Confirmations
  • Most of the filters and action hooks triggered by a regular form submission. Note: validation filters such as gform_pre_validation, gform_field_validation, and gform_validation will be triggered.

If you require any of the above see Submitting Forms with the GFAPI.

Source Code

public static function validate_form( $form_id, $input_values = array(), $field_values = array(), $target_page = 0, $source_page = 1 ) {}

This method is located in /includes/api.php.

Parameters

ParamTypeDescription
$form_idintegerThe ID of the form this submission belongs to.
$input_valuesarrayAn associative array containing the values to be validated using the field input names as the keys.
Will be merged into the $_POST.
The expected input names are identical to the input names found in the form markup. If you have any doubts about the name of an input, use your browsers developer tools to inspect the inputs via the form preview page.
$field_valuesarrayOptional.
An array of dynamic population parameter keys with their corresponding values used to populate the fields.
Overwrites $_POST['gform_field_values'].
$target_pageintegerOptional.
Default is 0.
For multi-page forms; indicates which page would be loaded next if the current page passes validation.
Overwrites $_POST[ 'gform_target_page_number_' . $form_id ].
$source_pageintegerOptional.
Default is 1.
For multi-page forms; indicates which page was active when the values were submitted for validation.
Overwrites $_POST[ 'gform_source_page_number_' . $form_id ].

Returns

An associative array containing the result properties or a WP_Error instance if the form can’t be found, isn’t active, is trashed, doesn’t have any fields, or requires login.

KeyTypeDescription
is_validboolThe form validation result.
validation_messagesarrayAn array of validation error messages.
page_numberintegerFor multi-page forms.
The page that should be displayed.
source_page_numberintegerFor multi-page forms.
The page that was submitted.
is_spamboolOnly present when is_valid is true.
Indicates if the submission has been identified as spam.

Usage Examples

Form Submission

This example shows how you can submit values for validation and handle the result.

$form_id                    = 52;
$input_values               = array();
$input_values['input_1']    = 'Single line text';
$input_values['input_2_3']  = 'First name';
$input_values['input_2_6']  = 'Last name';
$input_values['input_5']    = 'A paragraph of text.';

$result = GFAPI::validate_form( $form_id, $input_values );
if ( is_wp_error( $result ) ) {
	$error_message = $result->get_error_message();
	// Do something with the error message.
	return;
}

if ( ! rgar( $result, 'is_valid' ) ) {
	$error_message = 'Submission is invalid.';
	$field_errors  = rgar( $result, 'validation_messages', array() );
	// Do something with the message and errors.
	return;
} else {
	// Do something with the valid values.
}