As you may already know, with
WordPress Customizer API
theme developers are able to create settings for their themes which
allow site owners to fine tune things like color scheme, background
image and other custom options and see a preview of these changes in
real time.
Since we should never trust user input, the Customizer API requires
to define a callback function for each setting to validate and sanitize
input. Unfortunately I often run into the problem that I don’t know or
don’t remember the proper WordPress sanitization function for a
particular setting. That’s why I created this tutorial.
The following code examples below will demonstrate how to define sanitization callback functions for various data types. For order’s sake, the codes also include the method to add a section and a setting in Theme Customizer.
Jump to the code with a click:
How to sanitize radio box
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
|
function theme_slug_customizer( $wp_customize ) {
$wp_customize->add_section(
'theme_slug_customizer_your_section',
array(
'title' => esc_html__( 'Your Section', 'theme_slug' ),
'priority' => 150
)
);
function theme_slug_sanitize_radio( $input, $setting ){
$input = sanitize_key($input);
$choices = $setting->manager->get_control( $setting->id )->choices;
return ( array_key_exists( $input, $choices ) ? $input : $setting->default );
}
$wp_customize->add_setting(
'theme_slug_customizer_radio',
array(
'sanitize_callback' => 'theme_slug_sanitize_radio'
)
);
$wp_customize->add_control(
'theme_slug_customizer_radio',
array(
'label' => esc_html__( 'Your Setting with Radio Box', 'theme_slug' ),
'section' => 'theme_slug_customizer_your_section',
'type' => 'radio',
'choices' => array(
'one' => esc_html__('Choice One','theme_slug'),
'two' => esc_html__('Choice Two','theme_slug'),
'three' => esc_html__('Choice Three','theme_slug')
)
)
);
}
add_action( 'customize_register', 'theme_slug_customizer' );
|
How to sanitize checkbox
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
|
function theme_slug_customizer( $wp_customize ) {
$wp_customize->add_section(
'theme_slug_customizer_your_section',
array(
'title' => esc_html__( 'Your Section', 'theme_slug' ),
'priority' => 150
)
);
function theme_slug_sanitize_checkbox( $input ){
return ( isset( $input ) ? true : false );
}
$wp_customize->add_setting(
'theme_slug_customizer_checkbox',
array(
'default' => '',
'sanitize_callback' => 'theme_slug_sanitize_checkbox'
)
);
$wp_customize->add_control(
'theme_slug_customizer_checkbox',
array(
'label' => esc_html__( 'Your Setting with Checkbox', 'theme_slug' ),
'section' => 'theme_slug_customizer_your_section',
'type' => 'checkbox'
)
);
}
add_action( 'customize_register', 'theme_slug_customizer' );
|
How to sanitize select options
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
|
function theme_slug_customizer( $wp_customize ) {
$wp_customize->add_section(
'theme_slug_customizer_your_section',
array(
'title' => esc_html__( 'Your Section', 'theme_slug' ),
'priority' => 150
)
);
function theme_slug_sanitize_select( $input, $setting ){
$input = sanitize_key($input);
$choices = $setting->manager->get_control( $setting->id )->choices;
return ( array_key_exists( $input, $choices ) ? $input : $setting->default );
}
$wp_customize->add_setting(
'theme_slug_customizer_select',
array(
'sanitize_callback' => 'theme_slug_sanitize_select'
)
);
$wp_customize->add_control(
'theme_slug_customizer_select',
array(
'label' => esc_html__( 'Your Setting with select', 'theme_slug' ),
'section' => 'theme_slug_customizer_your_section',
'type' => 'select',
'choices' => array(
'' => esc_html__('Please select','theme_slug'),
'one' => esc_html__('Choice One','theme_slug'),
'two' => esc_html__('Choice Two','theme_slug'),
'three' => esc_html__('Choice Three','theme_slug')
)
)
);
}
add_action( 'customize_register', 'theme_slug_customizer' );
|
How to sanitize text input and how to sanitize textarea
If we want to allow simple text only, it’s enough to call
wp_filter_nohtml_kses() native function for
sanitize_callback directly.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
|
function theme_slug_customizer( $wp_customize ) {
$wp_customize->add_section(
'theme_slug_customizer_your_section',
array(
'title' => esc_html__( 'Your Section', 'theme_slug' ),
'priority' => 150
)
);
$wp_customize->add_setting(
'theme_slug_customizer_text',
array(
'sanitize_callback' => 'wp_filter_nohtml_kses'
)
);
$wp_customize->add_control(
'theme_slug_customizer_text',
array(
'label' => esc_html__( 'Your Setting with text input', 'theme_slug' ),
'section' => 'theme_slug_customizer_your_section',
'type' => 'text'
)
);
}
add_action( 'customize_register', 'theme_slug_customizer' );
|
How to sanitize email address
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
|
function theme_slug_customizer( $wp_customize ) {
$wp_customize->add_section(
'theme_slug_customizer_your_section',
array(
'title' => esc_html__( 'Your Section', 'theme_slug' ),
'priority' => 150
)
);
$wp_customize->add_setting(
'theme_slug_customizer_email',
array(
'sanitize_callback' => 'sanitize_email'
)
);
$wp_customize->add_control(
'theme_slug_customizer_email',
array(
'label' => esc_html__( 'Your Setting with email input', 'theme_slug' ),
'section' => 'theme_slug_customizer_your_section',
'type' => 'email'
)
);
}
add_action( 'customize_register', 'theme_slug_customizer' );
|
How to sanitize URL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
|
function theme_slug_customizer( $wp_customize ) {
$wp_customize->add_section(
'theme_slug_customizer_your_section',
array(
'title' => esc_html__( 'Your Section', 'theme_slug' ),
'priority' => 150
)
);
$wp_customize->add_setting(
'theme_slug_customizer_url',
array(
'sanitize_callback' => 'esc_url_raw'
)
);
$wp_customize->add_control(
'theme_slug_customizer_url',
array(
'label' => esc_html__( 'Your Setting with URL input', 'theme_slug' ),
'section' => 'theme_slug_customizer_your_section',
'type' => 'url'
)
);
}
add_action( 'customize_register', 'theme_slug_customizer' );
|
How to sanitize number
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
|
function theme_slug_customizer( $wp_customize ) {
$wp_customize->add_section(
'theme_slug_customizer_your_section',
array(
'title' => esc_html__( 'Your Section', 'theme_slug' ),
'priority' => 150
)
);
$wp_customize->add_setting(
'theme_slug_customizer_number',
array(
'sanitize_callback' => 'absint'
)
);
$wp_customize->add_control(
'theme_slug_customizer_number',
array(
'label' => esc_html__( 'Your Setting with number input', 'theme_slug' ),
'section' => 'theme_slug_customizer_your_section',
'type' => 'number'
)
);
}
add_action( 'customize_register', 'theme_slug_customizer' );
|
How to sanitize drop-down pages
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
|
function theme_slug_customizer( $wp_customize ) {
$wp_customize->add_section(
'theme_slug_customizer_your_section',
array(
'title' => esc_html__( 'Your Section', 'theme_slug' ),
'priority' => 150
)
);
$wp_customize->add_setting(
'theme_slug_customizer_dropdown_pages',
array(
'sanitize_callback' => 'absint'
)
);
$wp_customize->add_control(
'theme_slug_customizer_dropdown_pages',
array(
'label' => esc_html__( 'Your Setting with dropdown_pages input', 'theme_slug' ),
'section' => 'theme_slug_customizer_your_section',
'type' => 'dropdown-pages'
)
);
}
add_action( 'customize_register', 'theme_slug_customizer' );
|
How to sanitize file input
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
|
function theme_slug_customizer( $wp_customize ) {
$wp_customize->add_section(
'theme_slug_customizer_your_section',
array(
'title' => esc_html__( 'Your Section', 'theme_slug' ),
'priority' => 150
)
);
function theme_slug_sanitize_file( $file, $setting ) {
$mimes = array(
'jpg|jpeg|jpe' => 'image/jpeg',
'gif' => 'image/gif',
'png' => 'image/png'
);
$file_ext = wp_check_filetype( $file, $mimes );
return ( $file_ext['ext'] ? $file : $setting->default );
}
$wp_customize->add_setting(
'theme_slug_customizer_file',
array(
'sanitize_callback' => 'theme_slug_sanitize_file'
)
);
$wp_customize->add_control(
new WP_Customize_Upload_Control(
$wp_customize,
'theme_slug_customizer_file',
array(
'label' => __( 'Your Setting with file input', 'theme_slug' ),
'section' => 'theme_slug_customizer_your_section'
)
)
);
}
add_action( 'customize_register', 'theme_slug_customizer' );
|
How to sanitize CSS
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
|
function theme_slug_customizer( $wp_customize ) {
$wp_customize->add_section(
'theme_slug_customizer_your_section',
array(
'title' => esc_html__( 'Your Section', 'theme_slug' ),
'priority' => 150
)
);
$wp_customize->add_setting(
'theme_slug_customizer_css',
array(
'sanitize_callback' => 'wp_strip_all_tags'
)
);
$wp_customize->add_control(
'theme_slug_customizer_css',
array(
'label' => esc_html__( 'Your Setting with CSS input', 'theme_slug' ),
'section' => 'theme_slug_customizer_your_section',
'type' => 'textarea'
)
);
}
add_action( 'customize_register', 'theme_slug_customizer' );
|
How to sanitize HTML color code
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
|
function theme_slug_customizer( $wp_customize ) {
$wp_customize->add_section(
'theme_slug_customizer_your_section',
array(
'title' => esc_html__( 'Your Section', 'theme_slug' ),
'priority' => 150
)
);
$wp_customize->add_setting(
'theme_slug_customizer_color',
array(
'default' => '#000000',
'sanitize_callback' => 'sanitize_hex_color'
)
);
$wp_customize->add_control(
new WP_Customize_Color_Control(
$wp_customize,
'theme_slug_customizer_color',
array(
'label' => __( 'Your Setting with color input', 'theme_slug' ),
'section' => 'theme_slug_customizer_your_section'
)
)
);
}
add_action( 'customize_register', 'theme_slug_customizer' );
|
How to sanitize HTML code
Use
wp_kses_post() function which keeps only HTML tags which are allowed in post content as well.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
|
function theme_slug_customizer( $wp_customize ) {
$wp_customize->add_section(
'theme_slug_customizer_your_section',
array(
'title' => esc_html__( 'Your Section', 'theme_slug' ),
'priority' => 150
)
);
$wp_customize->add_setting(
'theme_slug_customizer_html_code',
array(
'sanitize_callback' => 'wp_kses_post'
)
);
$wp_customize->add_control(
'theme_slug_customizer_html_code',
array(
'label' => esc_html__( 'Your Setting with HTML code', 'theme_slug' ),
'section' => 'theme_slug_customizer_your_section',
'type' => 'textarea'
)
);
}
add_action( 'customize_register', 'theme_slug_customizer' );
|
Alternatively you can use
wp_kses() function where you can define the allowed HTML tags and attributes like this:
1
2
3
4
5
6
7
8
9
10
11
|
$allowed_html = array(
'a' => array(
'href' => array(),
'title' => array()
),
'br' => array(),
'em' => array(),
'strong' => array(),
);
wp_kses($input, $allowed_html);
|
How to sanitize Javascript code
We are 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
|
function theme_slug_customizer( $wp_customize ) {
$wp_customize->add_section(
'theme_slug_customizer_your_section',
array(
'title' => esc_html__( 'Your Section', 'theme_slug' ),
'priority' => 150
)
);
function theme_slug_sanitize_js_code($input){
return base64_encode($input);
}
function theme_slug_escape_js_output($input){
return esc_textarea( base64_decode($input) );
}
$wp_customize->add_setting(
'theme_slug_customizer_js_code',
array(
'sanitize_callback' => 'theme_slug_sanitize_js_code',
'sanitize_js_callback' => 'theme_slug_escape_js_output'
)
);
$wp_customize->add_control(
'theme_slug_customizer_js_code',
array(
'label' => esc_html__( 'Your Setting with JS code', 'theme_slug' ),
'section' => 'theme_slug_customizer_your_section',
'type' => 'textarea'
)
);
}
add_action( 'customize_register', 'theme_slug_customizer' );
|
List of WordPress sanitization functions
In case I forgot something, here is a list of sanitize functions. Maybe one of them is more suitable for your project.
I also give you some PHP functions to fill some gaps.
https://divpusher.com/blog/wordpress-customizer-sanitization-examples/#radio
Normally there are 3 common “strange” characters: EF, BB, BF.
How to remove the character ?
There are multiple ways to fix the issue. for example: write a java script function to replace the strange character to a empty string.
But, we think the most efficient way is using the free tool NotePad++ to convert the original file to UTF-8 (without BOM) format.
Menu Encoding –> Convert to UTF-8.
After you did the converting, the strange space on web page will gone.
http://www.gogototo.com/resolve-the-strange-character-65279-in-wordpress-web-page.html