Validating Form Submissions with the GFAPI

Introduction
Source Code
Parameters
Returns
Usage Examples
Form Submission

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

Param	Type	Description
$form_id	integer	The ID of the form this submission belongs to.
$input_values	array	An 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_values	array	Optional. An array of dynamic population parameter keys with their corresponding values used to populate the fields. Overwrites `$_POST['gform_field_values']`.
$target_page	integer	Optional. 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_page	integer	Optional. 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.

Key	Type	Description
is_valid	bool	The form validation result.
validation_messages	array	An array of validation error messages.
page_number	integer	For multi-page forms. The page that should be displayed.
source_page_number	integer	For multi-page forms. The page that was submitted.
is_spam	bool	Only 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.
}