do_action( 'wpforms_process_validate_payment-checkbox', string|int $field_id, mixed $field_submit, array $form_data )

Description

The wpforms_process_validate_payment-checkbox action fires for each Checkbox Items payment field while WPForms validates a submitted form, before any field value is formatted and before the entry is saved.

This action is available since WPForms 1.4.0.

More Information

WPForms_Process::process() loops over every field in $form_data['fields'] and calls do_action( "wpforms_process_validate_{$field_type}", $field_id, $field_submit, $this->form_data ) for each one. This hook is the instance for the payment-checkbox field type. It fires on every submission of a form that contains the field, whether or not the visitor filled it in. The file lives in includes/, so it fires in Lite and Pro.

This hook is an instance of do_action( "wpforms_process_validate_{$field_type}", $field_id, $field_submit, $form_data ). Other instances are wpforms_process_validate_payment-single for the Single Item field and wpforms_process_validate_checkbox for the standard Checkboxes field.

The field class registers its own validate() method on this hook at priority 10 with three arguments. That callback adds the required-field error, rejects choice IDs that do not exist in the field settings, and enforces the field’s choice limit. A callback added later at the same priority runs after it and overwrites the same error slot.

To reject the submission, write a message to wpforms()->obj( 'process' )->errors[ $form_data['id'] ][ $field_id ]. After the loop, the wpforms_process_initial_errors filter runs on the collected errors; Conditional Logic uses it to drop errors from hidden fields. Values are not sanitized at this point. Sanitizing happens later in wpforms_process_format_{$field_type}.

Source

wpforms/includes/class-process.php

Example

Require between two and five checked items in one Checkbox Items field on one form, and stop the submission with an error under the field when the count is outside that range.

/**
 * Require between two and five checked items in a Checkbox Items field.
 *
 * @link https://wpforms.com/developers/wpforms_process_validate_payment-checkbox/
 *
 * @param string|int $field_id     Field ID.
 * @param mixed      $field_submit Submitted field value (raw data).
 * @param array      $form_data    Form data and settings.
 */
function wpf_dev_process_validate_payment_checkbox( $field_id, $field_submit, $form_data ) {

    // Only run on my form with ID = 143, remember to change this to match your form ID.
    if ( absint( $form_data['id'] ) !== 143 ) {
        return;
    }

    // Only run on the Checkbox Items field with ID = 21, remember to change this to match your field ID.
    if ( absint( $field_id ) !== 21 ) {
        return;
    }

    $min   = 2;
    $max   = 5;
    $count = is_array( $field_submit ) ? count( $field_submit ) : 0;

    if ( $count < $min ) {
        wpforms()->obj( 'process' )->errors[ $form_data['id'] ][ $field_id ] = sprintf(
            /* translators: %d - minimum number of choices. */
            esc_html__( 'Please select a minimum of %d choices.', 'wpforms' ),
            $min
        );

        return;
    }

    if ( $count > $max ) {
        wpforms()->obj( 'process' )->errors[ $form_data['id'] ][ $field_id ] = sprintf(
            /* translators: %d - maximum number of choices. */
            esc_html__( 'Please select a maximum of %d choices.', 'wpforms' ),
            $max
        );
    }
}
add_action( 'wpforms_process_validate_payment-checkbox', 'wpf_dev_process_validate_payment_checkbox', 10, 3 );

Reference Article

• Setting a Minimum Number of Choices for a Checkbox