validations

The set of validations used to validate the value of the control and it will prompt an error message if an error occurs based on the defined validations. For additional information about validate_callback, please check the official Customizer API.

Attributes

This is the validation's comprehensive information.

Type	Required	Default
array	no	empty

Basic Usage

EXAMPLE 1

In this example, the text control's value will be validated using the Handy's built-in validation required.

 
/**
 * Text Control.
 *
 * required – prompt error message if the value is empty.
 */
Handy::control( 'text', [
    'id'          => 'text_id',
    'section'     => 'layout_section',
    'label'       => esc_html__( 'Text Control', 'textdomain' ),
    'priority'    => 1,
    'validations' => [ 'required' ]
]);

EXAMPLE 2

In this example, the text control's value will be validated multiple times using the Handy's built-in validations required, is_integer and less_than.

 
/**
 * Text Control.
 *
 * required – prompt error message if the value is empty.
 * is_integer – prompt error message if the value is an invalid integer.
 * less_than – prompt error message if the value is '>=' to number.
 */
Handy::control( 'text', [
    'id'          => 'text_id',
    'section'     => 'layout_section',
    'label'       => esc_html__( 'Enter Age', 'textdomain' ),
    'priority'    => 1,
    'validations' => [ 'required', 'is_integer', 'less_than[18]' ]
]);

EXAMPLE 3

In this example, the text control's value will be validated using a custom validation.

 
/**
 * Text Control.
 *
 * required – prompt error message if the value is empty.
 */
Handy::control( 'text', [
    'id'          => 'text_id',
    'section'     => 'layout_section',
    'label'       => esc_html__( 'Enter Name', 'textdomain' ),
    'priority'    => 1,
    'validations' => [ 'required', 'is_value_has_number' ]
]);

/**
 * Custom validation. Prompt error message if value contains a number.
 *
 * @param object  $validity  Contains the validation prompt.
 * @param mixed   $value     Contains the control's value.
 * @return object
 */
function is_value_has_number( $validity, $value ) {
    if ( preg_match( '~[0-9]+~', $value ) ) {
        // add error message if regex is true.
        $validity->add( 'error', 'Invalid the value contains a number.' );
    }

    // always return $validity.
    return $validity;
}

Built-In Validations

Handy provides a comprehensive validations and data prepping functions that helps minimize the amount of code you will write. The built-in validations that are available in Handy are listed in the list below.

# required

Prompt an error message if the control's value is empty.

Parameter	Message
none	Required Field.

 
$args = [
    'validations' => [ 'required' ]
];

# valid_attachment

Prompt an error message if the attachment file type or extension is not found in predetermined extensions.

Parameter	Message
string	The specified file [filename] is not allowed. Only files with the following extensions are allowed: [file_extentions].

 
$args = [
    'validations' => [ 'valid_attachment[jpg,png,webp]' ]
];

# valid_color

Prompt an error message if the control's value is an invalid color.

Parameter	Message
string	The selected color contains an invalid color format. Only color with format [color_formats] are only allowed.

 
$args = [
    'validations' => [ 'valid_color[hex,rgb]' ]
];

# valid_dates

Prompt an error message if the control's value contains an invalid date based in predetermined date format.

Parameter	Message
string	The selected dates contains an invalid date format. Only date with format [data_format] are only allowed.

 
$args = [
    'validations' => [ 'valid_dates[Y-m-d]' ]
];

# valid_email

Prompt an error message if the control's value is an invalid email address.

Parameter	Message
none	Invalid email address.

 
$args = [
    'validations' => [ 'valid_email' ]
];

# valid_ip

Prompt an error message if the control's value is an invalid ip address.

Parameter	Message
none	Invalid IP address.

 
$args = [
    'validations' => [ 'valid_ip' ]
];

# valid_size

Prompt an error message if the control's value is an invalid size.

Parameter	Message
string	Invalid size.

 
$args = [
    'validations' => [ 'valid_size[px,em,rem]' ]
];

# valid_time

Prompt an error message if the control's value contains an invalid time based in predetermined time format.

Parameter	Message
string	The selected time contains an invalid time format. Only time with format [time_format] are only allowed.

 
$args = [
    'validations' => [ 'valid_time[h:i]' ]
];

# valid_url

Prompt an error message if the control's value is an invalid URL.

Parameter	Message
none	Invalid url.

 
$args = [
    'validations' => [ 'valid_url' ]
];

# alpha

Prompt an error message if the control's value contains a none alphabetical character.

Parameter	Message
none	Must contain only alphabetical characters.

 
$args = [
    'validations' => [ 'alpha' ]
];

# alpha_numeric

Prompt an error message if the control's value contains a none alphabetical and numeric character.

Parameter	Message
none	Must contain only numeric and alphabetical characters.

 
$args = [
    'validations' => [ 'alpha_numeric' ]
];

# is_float

Prompt an error message if the value is an invalid float.

Parameter	Message
none	Invalid float number.

 
$args = [
    'validations' => [ 'is_float' ]
];

# is_integer

Prompt an error message if the control's value is an invalid integer.

Parameter	Message
none	Invalid integer number.

 
$args = [
    'validations' => [ 'is_integer' ]
];

# is_number

Prompt an error message if the control's value is an invalid number.

Parameter	Message
none	Invalid number.

 
$args = [
    'validations' => [ 'is_number' ]
];

# exact_length

Prompt an error message if the control's value characters length is not equal to length.

Parameter	Message
integer	Total characters must be exact [total_characters].

 
$args = [
    'validations' => [ 'exact_length[10]' ]
];

# min_length

Prompt an error message if the control's value characters length is less than the minimum.

Parameter	Message
integer	Total characters must not be less than [minimum_characters].

 
$args = [
    'validations' => [ 'min_length[10]' ]
];

# max_length

Prompt an error message if the control's value characters length is greater than the maximum.

Parameter	Message
integer	Total characters must not exceed [maximum_characters].

 
$args = [
    'validations' => [ 'max_length[10]' ]
];

# total_words

Prompt an error message if the control's value total words count is not equal to number.

Parameter	Message
integer	Total count of words must be exact [total_words].

 
$args = [
    'validations' => [ 'total_words[10]' ]
];

# total_words_greater_than

Prompt an error message if the control's value total words count is less than the maximum.

Parameter	Message
integer	Total count of words must be greater than or equal to [maximum_words].

 
$args = [
    'validations' => [ 'total_words_greater_than[10]' ]
];

# total_words_less_than

Prompt an error message if the control's value total words count is greater than the minimum.

Parameter	Message
integer	Total count of words must be less than or equal to [minimum_words].

 
$args = [
    'validations' => [ 'total_words_less_than[10]' ]
];

# greater_than

Prompt an error message if the control's value is less than number.

Parameter	Message
integer	Value must be greater than [number].

 
$args = [
    'validations' => [ 'greater_than[10]' ]
];

# greater_than_equal_to

Prompt an error message if the control's value is less than or equal to number.

Parameter	Message
integer	Value must be greater than or equal to [number].

 
$args = [
    'validations' => [ 'greater_than_equal_to[10]' ]
];

# less_than

Prompt an error message if the control's value is greater than number.

Parameter	Message
integer	Value must be less than [number].

 
$args = [
    'validations' => [ 'less_than[10]' ]
];

# less_than_equal_to

Prompt an error message if the control's value is greater than or equal to number.

Parameter	Message
integer	Value must be less than or equal to [number].

 
$args = [
    'validations' => [ 'less_than_equal_to[10]' ]
];

# in_choices

Prompt an error message if the control's value is not found in predetermined choices.

Parameter	Message
string	Value not found in the choices [choices].

 
$args = [
    'validations' => [ 'in_choices[apple,grape,melon]' ]
];

# not_in_choices

Prompt an error message if the control's value is found in predetermined choices.

Parameter	Message
string	Value must not exists in the choices [choices].

 
$args = [
    'validations' => [ 'not_in_choices[apple,grape,melon]' ]
];

# values_in_choices

Prompt an error message if a certain control's value in array values is not found in predetermined choices.

Parameter	Message
string	A certain value is not found in the choices [choices].

 
$args = [
    'validations' => [ 'values_in_choices[apple,grape,melon]' ]
];

# values_not_in_choices

Prompt an error message if a certain control's value in array values is found in predetermined choices.

Parameter	Message
string	A certain value must not exists in the choices [choices].

 
$args = [
    'validations' => [ 'values_not_in_choices[apple,grape,melon]' ]
];

# equal_to_setting

Prompt an error message if the control's value is not equal to a value of a certain setting or control.

Parameter	Message
string	Value must be equal to the value of setting: [control_id].

 
$args = [
    'validations' => [ 'equal_to_setting[text_id]' ]
];

# not_equal_to_setting

Prompt an error message if the value is equal to a control's value of a certain setting or control.

Parameter	Message
string	Value must not be equal to the value of setting: [control_id].

 
$args = [
    'validations' => [ 'not_equal_to_setting[text_id]' ]
];