Validate Field Filter Hook

Overview

The suredonation_validate_field filter allows developers to add custom validation rules for individual SureDonation form fields.

The filter runs after SureDonation’s core validation for each field. You can use it to validate custom field types or apply additional validation rules that are not included in the default validation.

If your callback returns a non-empty string, the field is considered invalid, and the returned string is displayed as the field’s validation error message.

When This Filter Runs

The filter is applied during form data validation, after SureDonation performs its built-in validation for the field.

It is useful when you need to:

• Add custom validation rules.
• Validate custom field blocks.
• Apply business-specific validation requirements.
• Add validation based on the submitted field value.
• Provide custom validation error messages.

Filter Signature

apply_filters( 'suredonation_validate_field', $error, $value, $config, $form_id, $block_name );

apply_filters( 'suredonation_validate_field', $error, $value, $config, $form_id, $block_name );

Parameters

Return Value

Your callback should return a string.

When core validation has already returned an error, it is recommended to return the existing $error instead of replacing it unless you intentionally want to override the message.

Basic Usage

Use add_filter() to register your custom validation callback.

add_filter( 'suredonation_validate_field', 'your_custom_function', 10, 5 );

function your_custom_function( $error, $value, $config, $form_id, $block_name ) {

    // Return a non-empty string to fail validation.

    return $error;

}

add_filter( 'suredonation_validate_field', 'your_custom_function', 10, 5 );

function your_custom_function( $error, $value, $config, $form_id, $block_name ) {

    // Return a non-empty string to fail validation.

    return $error;

}

Example: Validate a Custom Field

The following example validates a custom field block and requires the submitted value to start with MY-.

add_filter( 'suredonation_validate_field', 'mysite_validate_field', 10, 5 );

function mysite_validate_field( $error, $value, $config, $form_id, $block_name ) {

    // Only validate our custom block

    // and do not override an existing error.

    if ( '' === $error && 'mysite/custom-field' === $block_name ) {

        if ( ! str_starts_with( $value, 'MY-' ) ) {

            return __( 'This code must start with "MY-".', 'my-plugin' );

        }

    }

    return $error;

}

add_filter( 'suredonation_validate_field', 'mysite_validate_field', 10, 5 );

function mysite_validate_field( $error, $value, $config, $form_id, $block_name ) {

    // Only validate our custom block

    // and do not override an existing error.

    if ( '' === $error && 'mysite/custom-field' === $block_name ) {

        if ( ! str_starts_with( $value, 'MY-' ) ) {

            return __( 'This code must start with "MY-".', 'my-plugin' );

        }

    }

    return $error;

}

How the Example Works

1. The callback checks whether core validation has already returned an error.
2. It checks whether the field belongs to mysite/custom-field.
3. It verifies that the submitted value starts with MY-.
4. If the value does not meet the requirement, a custom error message is returned.
5. If the value is valid, the existing $error is returned.

Recommended Usage

When adding custom validation, check the existing $error before applying your own validation.

if ( '' === $error ) {

    // Apply custom validation.

}

if ( '' === $error ) {

    // Apply custom validation.

}

This prevents your custom validation from unnecessarily replacing an error generated by SureDonation’s core validation.

Related Hooks

• suredonation_validatable_blocks: Controls which blocks are included in field validation.
• suredonation_field_block_config: Filters the stored configuration for a donation form field.
• suredonation_default_validation_messages: Filters the default validation messages used by SureDonation.