The Customizer API demands a callback function be defined for each setting to validate and sanitize input because we should never trust user input. Unfortunately, I frequently have the issue of not knowing or remembering the appropriate WordPress sanitization function for a specific setup.
The definition of sanitization callback functions for different data types is shown in the following code snippets. The codes also contain how to create a section and a setting in Theme Customizer for the purpose of order.
/**
* SANITIZE RADIO BOX
*
* @param [type] $wp_customize
* @return void
*/
function weszty_web_customizer_radio( $wp_customize ) {
$wp_customize->add_section(
'weszty_web_customizer_radio_section',
array(
'title' => esc_html__( 'Your Section', 'weszty_web' ),
'priority' => 150
)
);
// radio box sanitization function
function weszty_web_sanitize_radio( $input, $setting ) {
// input must be a slug: lowercase alphanumeric characters, dashes and underscores are allowed only
$input = sanitize_key( $input );
// get the list of possible radio box options
$choices = $setting->manager->get_control( $setting->id )->choices;
// return input if valid or return default option
return ( array_key_exists( $input, $choices ) ? $input : $setting->default );
}
// add setting to your section
$wp_customize->add_setting(
'weszty_web_customizer_radio',
array(
'sanitize_callback' => 'weszty_web_sanitize_radio'
)
);
$wp_customize->add_control(
'weszty_web_customizer_radio',
array(
'label' => esc_html__( 'Your Setting with Radio Box', 'weszty_web' ),
'section' => 'weszty_web_customizer_radio_section',
'type' => 'radio',
'choices' => array(
'one' => esc_html__( 'Choice One', 'weszty_web' ),
'two' => esc_html__( 'Choice Two', 'weszty_web' ),
'three' => esc_html__( 'Choice Three', 'weszty_web' )
)
)
);
}
add_action( 'customize_register', 'weszty_web_customizer_radio' );
/**
* SANITIZE CHECKBOX
*
* @param [type] $wp_customize
* @return void
*/
function weszty_web_customizer_checkbox( $wp_customize ) {
$wp_customize->add_section(
'weszty_web_customizer_checkbox_section',
array(
'title' => esc_html__( 'Your Section', 'weszty_web' ),
'priority' => 150
)
);
// checkbox sanitization function
function weszty_web_sanitize_checkbox( $input ) {
// returns true if checkbox is checked
return ( isset( $input ) ? true : false );
}
// add setting to your section
$wp_customize->add_setting(
'weszty_web_customizer_checkbox_checkbox',
array(
'default' => '',
'sanitize_callback' => 'weszty_web_sanitize_checkbox'
)
);
$wp_customize->add_control(
'weszty_web_customizer_checkbox_checkbox',
array(
'label' => esc_html__( 'Your Setting with Checkbox', 'weszty_web' ),
'section' => 'weszty_web_customizer_checkbox_section',
'type' => 'checkbox'
)
);
}
add_action( 'customize_register', 'weszty_web_customizer_checkbox' );/**
* SANITIZE SELECT OPTIONS
*
* @param [type] $wp_customize
* @return void
*/
function weszty_web_customizer_select( $wp_customize ) {
$wp_customize->add_section(
'weszty_web_customizer_section',
array(
'title' => esc_html__( 'Your Section', 'weszty_web' ),
'priority' => 150
)
);
// select sanitization function
function weszty_web_sanitize_select( $input, $setting ) {
// input must be a slug: lowercase alphanumeric characters, dashes and underscores are allowed only
$input = sanitize_key( $input );
// get the list of possible select options
$choices = $setting->manager->get_control( $setting->id )->choices;
// return input if valid or return default option
return ( array_key_exists( $input, $choices ) ? $input : $setting->default );
}
// add setting to your section
$wp_customize->add_setting(
'weszty_web_customizer_select',
array(
'sanitize_callback' => 'weszty_web_sanitize_select'
)
);
$wp_customize->add_control(
'weszty_web_customizer_select',
array(
'label' => esc_html__( 'Your Setting with select', 'weszty_web' ),
'section' => 'weszty_web_customizer_section',
'type' => 'select',
'choices' => array(
'' => esc_html__( 'Please select','weszty_web' ),
'one' => esc_html__( 'Choice One','weszty_web' ),
'two' => esc_html__( 'Choice Two','weszty_web' ),
'three' => esc_html__( 'Choice Three','weszty_web' )
)
)
);
}
add_action( 'customize_register', 'weszty_web_customizer_select' );It is sufficient to use wp_filter_nohtml_kses() directly in the callback to allow simple text only.
/**
* SANITIZE TEXT AND TEXTAREA INPUT
*
* @param [type] $wp_customize
* @return void
*/
function weszty_web_customizer_input( $wp_customize ) {
$wp_customize->add_section(
'weszty_web_customizer_input_section',
array(
'title' => esc_html__( 'Your Section', 'weszty_web' ),
'priority' => 150
)
);
// add setting to your section
$wp_customize->add_setting(
'weszty_web_customizer_input_text',
array(
'sanitize_callback' => 'wp_filter_nohtml_kses' // removes all HTML from content
)
);
$wp_customize->add_control(
'weszty_web_customizer_input_text',
array(
'label' => esc_html__( 'Your Setting with text input', 'weszty_web' ),
'section' => 'weszty_web_customizer_input_section',
'type' => 'text'
)
);
}
add_action( 'customize_register', 'weszty_web_customizer_input' );/**
* SANITIZE EMAIL
*
* @param [type] $wp_customize
* @return void
*/
function weszty_web_customizer_email( $wp_customize ) {
$wp_customize->add_section(
'weszty_web_customizer_section',
array(
'title' => esc_html__( 'Your Section', 'weszty_web' ),
'priority' => 150
)
);
// add setting to your section
$wp_customize->add_setting(
'weszty_web_customizer_email',
array(
'sanitize_callback' => 'sanitize_email' // removes all invalid characters
)
);
$wp_customize->add_control(
'weszty_web_customizer_email',
array(
'label' => esc_html__( 'Your Setting with email input', 'weszty_web' ),
'section' => 'weszty_web_customizer_section',
'type' => 'email'
)
);
}
add_action( 'customize_register', 'weszty_web_customizer_email' );/**
* SANITIZE URL
*
* @param [type] $wp_customize
* @return void
*/
function weszty_web_customizer_url( $wp_customize ) {
$wp_customize->add_section(
'weszty_web_customizer_section',
array(
'title' => esc_html__( 'Your Section', 'weszty_web' ),
'priority' => 150
)
);
// add setting to your section
$wp_customize->add_setting(
'weszty_web_customizer_url',
array(
'sanitize_callback' => 'esc_url_raw' // cleans URL from all invalid char
)
);
$wp_customize->add_control(
'weszty_web_customizer_url',
array(
'label' => esc_html__( 'Your Setting with URL input', 'weszty_web' ),
'section' => 'weszty_web_customizer_section',
'type' => 'url'
)
);
}
add_action( 'customize_register', 'weszty_web_customizer_url' );/**
* SANITIZE NUMBER
*
* @param [type] $wp_customize
* @return void
*/
function weszty_web_customizer_number( $wp_customize ) {
$wp_customize->add_section(
'weszty_web_customizer_section',
array(
'title' => esc_html__( 'Your Section', 'weszty_web' ),
'priority' => 150
)
);
// add setting to your section
$wp_customize->add_setting(
'weszty_web_customizer_number',
array(
'sanitize_callback' => 'absint' // converts value to a non-negative integer
)
);
$wp_customize->add_control(
'weszty_web_customizer_number',
array(
'label' => esc_html__( 'Your Setting with number input', 'weszty_web' ),
'section' => 'weszty_web_customizer_section',
'type' => 'number'
)
);
}
add_action( 'customize_register', 'weszty_web_customizer_number' );/**
* SANITIZE DROP-DOWN PAGES
*
* @param [type] $wp_customize
* @return void
*/
function weszty_web_customizer_drop_down( $wp_customize ) {
$wp_customize->add_section(
'weszty_web_customizer_section',
array(
'title' => esc_html__( 'Your Section', 'weszty_web' ),
'priority' => 150
)
);
// add setting to your section
$wp_customize->add_setting(
'weszty_web_customizer_drop_down',
array(
'sanitize_callback' => 'absint' // converts value to a non-negative integer
)
);
$wp_customize->add_control(
'weszty_web_customizer_drop_down',
array(
'label' => esc_html__( 'Your Setting with dropdown_pages input', 'weszty_web' ),
'section' => 'weszty_web_customizer_section',
'type' => 'dropdown-pages'
)
);
}
add_action( 'customize_register', 'weszty_web_customizer_drop_down' );/**
* SANITIZE FILE INPUT
*
* @param [type] $wp_customize
* @return void
*/
function weszty_web_customizer_file( $wp_customize ) {
$wp_customize->add_section(
'weszty_web_customizer_section',
array(
'title' => esc_html__( 'Your Section', 'weszty_web' ),
'priority' => 150
)
);
// file input sanitization function
function weszty_web_sanitize_file( $file, $setting ) {
// allowed file types
$mimes = array(
'jpg|jpeg|jpe' => 'image/jpeg',
'gif' => 'image/gif',
'png' => 'image/png'
);
// check file type from file name
$file_ext = wp_check_filetype( $file, $mimes );
// if file has a valid mime type return it, otherwise return default
return ( $file_ext['ext'] ? $file : $setting->default );
}
// add select setting to your section
$wp_customize->add_setting(
'weszty_web_customizer_file',
array(
'sanitize_callback' => 'weszty_web_sanitize_file'
)
);
$wp_customize->add_control(
new WP_Customize_Upload_Control(
$wp_customize,
'weszty_web_customizer_file',
array(
'label' => esc_html__( 'Your Setting with file input', 'weszty_web' ),
'section' => 'weszty_web_customizer_section'
)
)
);
}
add_action( 'customize_register', 'weszty_web_customizer_file' );/**
* SANITIZE CSS
*
* @param [type] $wp_customize
* @return void
*/
function weszty_web_customizer_css( $wp_customize ) {
$wp_customize->add_section(
'weszty_web_customizer_section',
array(
'title' => esc_html__( 'Your Section', 'weszty_web' ),
'priority' => 150
)
);
// add setting to your section
$wp_customize->add_setting(
'weszty_web_customizer_css',
array(
'sanitize_callback' => 'wp_strip_all_tags' // strip all HTML tags including script and style
)
);
$wp_customize->add_control(
'weszty_web_customizer_css',
array(
'label' => esc_html__( 'Your Setting with CSS input', 'weszty_web' ),
'section' => 'weszty_web_customizer_section',
'type' => 'textarea'
)
);
}
add_action( 'customize_register', 'weszty_web_customizer_css' );/**
* SANITIZE CSS HEX COLOR CODE
*
* @param [type] $wp_customize
* @return void
*/
function weszty_web_customizer_hex( $wp_customize ) {
$wp_customize->add_section(
'weszty_web_customizer_section',
array(
'title' => esc_html__( 'Your Section', 'weszty_web' ),
'priority' => 150
)
);
// add setting to your section
$wp_customize->add_setting(
'weszty_web_customizer_color',
array(
'default' => '#000000',
'sanitize_callback' => 'sanitize_hex_color' // validates 3 or 6 digit HTML hex color code
)
);
$wp_customize->add_control(
new WP_Customize_Color_Control(
$wp_customize,
'weszty_web_customizer_color',
array(
'label' => esc_html__( 'Your Setting with color input', 'weszty_web' ),
'section' => 'weszty_web_customizer_section'
)
)
);
}
add_action( 'customize_register', 'weszty_web_customizer_hex' );Use the wp_kses() method, which only saves HTML tags that are permitted in post content.
/**
* SANITIZE HTML
*
* @param [type] $wp_customize
* @return void
*/
function weszty_web_customizer_html( $wp_customize ) {
$wp_customize->add_section(
'weszty_web_customizer_section',
array(
'title' => esc_html__( 'Your Section', 'weszty_web' ),
'priority' => 150
)
);
// add setting to your section
$wp_customize->add_setting(
'weszty_web_customizer_html_code',
array(
'sanitize_callback' => 'wp_kses_post' // keeps only HTML tags that are allowed in post content
)
);
$wp_customize->add_control(
'weszty_web_customizer_html_code',
array(
'label' => esc_html__( 'Your Setting with HTML code', 'weszty_web' ),
'section' => 'weszty_web_customizer_section',
'type' => 'textarea'
)
);
}
add_action( 'customize_register', 'weszty_web_customizer_html' );As an alternative, you can define the permitted HTML tags and attributes using the wp_kses() method as follows:
$allowed_html = array(
'a' => array(
'href' => array(),
'title' => array()
),
'br' => array(),
'em' => array(),
'strong' => array(),
);
wp_kses( $input, $allowed_html );I will be using base64_encode() function to save the script in database properly and base64_decode() function to escape the script for the textarea in Customizer. Also use base64_decode() function on frontend to echo the script.
/**
* SANITIZE JAVASCRIPT
*
* @param [type] $wp_customize
* @return void
*/
function weszty_web_customizer_js( $wp_customize ) {
$wp_customize->add_section(
'weszty_web_customizer_section',
array(
'title' => esc_html__( 'Your Section', 'weszty_web' ),
'priority' => 150
)
);
// script input sanitization function
function weszty_web_sanitize_js_code( $input ) {
return base64_encode( $input );
}
// output escape function
function weszty_web_escape_js_output( $input ) {
return esc_textarea( base64_decode( $input ) );
}
// add setting to your section
$wp_customize->add_setting(
'weszty_web_customizer_js_code',
array(
'sanitize_callback' => 'weszty_web_sanitize_js_code', // encode for DB insert
'sanitize_js_callback' => 'weszty_web_escape_js_output' // escape script for the textarea
)
);
$wp_customize->add_control(
'weszty_web_customizer_js_code',
array(
'label' => esc_html__( 'Your Setting with JS code', 'weszty_web' ),
'section' => 'weszty_web_customizer_section',
'type' => 'textarea'
)
);
}
add_action( 'customize_register', 'weszty_web_customizer_js' );LIST OF OTHER WORDPRESS SANITIZATION FUNCTIONS
- absint() – converts value to positive integer, useful for numbers, IDs, etc.
- esc_url_raw() – for inserting URL in database safely
- sanitize_email() – strips out all characters that are not allowable in an email address
- sanitize_file_name() – removes special characters that are illegal in filenames on certain operating system
- sanitize_hex_color() – returns 3 or 6 digit hex color with #, or nothing
- sanitize_hex_color_no_hash() – the same as above but without a #
- sanitize_html_class() – sanitizes an HTML classname to ensure it only contains valid characters
- sanitize_key() – lowercase alphanumeric characters, dashes and underscores are allowed
- sanitize_mime_type() – useful to save mime type in DB, e.g. uploaded file’s type
- sanitize_option() – sanitizes values like update_option() and add_option() does for various option types. Here is the list of avaliable options: https://codex.wordpress.org/Function_Reference/sanitize_option#Notes
- sanitize_sql_orderby() – ensures a string is a valid SQL order by clause
- sanitize_text_field() – removes all HTML markup, as well as extra whitespace, leaves nothing but plain text
- sanitize_title() – returned value intented to be suitable for use in a URL
- sanitize_title_for_query() – used for querying the database for a value from URL
- sanitize_title_with_dashes() – same as above but it does not replace special accented characters
- sanitize_user() – sanitize username stripping out unsafe characters
- wp_filter_post_kses(), wp_kses_post() – it keeps only HTML tags which are allowed in post content as well
- wp_kses() – allows only HTML tags and attributes that you specify
- wp_kses_data() – sanitize content with allowed HTML Kses rules
- wp_rel_nofollow() – adds rel nofollow string to all HTML A elements in content
