do_action( 'wpforms_process_validate_name', string|int $field_id, mixed $field_submit, array $form_data )

Description

The wpforms_process_validate_name action fires validation on the Name field when the form is submitted, before any field value is sanitized.

More Information

The action fires inside WPForms_Process::process(). After the wpforms_process_before hooks run, the method loops over every field in $form_data['fields'] and fires this action once per field with the raw value from $_POST. The file lives in includes/, so the hook fires in both Lite and Pro.

This hook is an instance of do_action( "wpforms_process_validate_{$field_type}", $field_id, $field_submit, $form_data ). The same call fires wpforms_process_validate_email for the Email field and wpforms_process_validate_text for the Single Line Text field.

The Name field’s own validation runs on this same action. WPForms_Field::__construct() in includes/fields/class-base.php adds each field’s validate() method at priority 10 with three arguments. For the Name field, that method only enforces the Required setting: a non-empty string for the Simple format, or non-empty first and last values for the other formats. Other checks are yours to add.

To reject a submission, write a message to wpforms()->obj( 'process' )->errors[ $form_data['id'] ][ $field_id ]. Any error set during this loop stops processing before the entry is saved. Values are not sanitized until wpforms_process_format_{$field_type} runs later, so treat $field_submit as untrusted input.

Source

wpforms/includes/class-process.php

Example

Blocks a list of names from submitting one form. It handles both the Simple format (a string) and the First Last formats (an array) and shows the error on the field.

/**
 * Block specific names from submitting the form.
 *
 * @link https://wpforms.com/developers/wpforms_process_validate_name/
 *
 * @param string|int $field_id     Field ID as a numeric string.
 * @param mixed      $field_submit Submitted field value (raw data).
 * @param array      $form_data    Form data.
 */
function wpf_dev_block_name_validation( $field_id, $field_submit, $form_data ) {

    // Only run on the form with ID 143 and the Name field with ID 10. Remember to change both IDs to match your form.
    if ( absint( $form_data['id'] ) !== 143 || absint( $field_id ) !== 10 ) {
        return;
    }

    // The Simple format submits a string. First Last and First Middle Last submit an array.
    if ( is_array( $field_submit ) ) {
        $submitted_name = implode( ' ', array_filter( [ $field_submit['first'] ?? '', $field_submit['middle'] ?? '', $field_submit['last'] ?? '' ] ) );
    } else {
        $submitted_name = (string) $field_submit;
    }

    // Add the names to block.
    $blocked_names = [
        'John Doe',
        'Jane Doe',
    ];

    foreach ( $blocked_names as $name ) {
        if ( preg_match( '/\b' . preg_quote( $name, '/' ) . '\b/i', $submitted_name ) ) {
            wpforms()->obj( 'process' )->errors[ $form_data['id'] ][ $field_id ] = esc_html__( 'This name cannot be used to submit the form.', 'wpforms' );
            return;
        }
    }
}
add_action( 'wpforms_process_validate_name', 'wpf_dev_block_name_validation', 10, 3 );

Reference Article

• How to Block Names From Completing Your Form