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:
Alternatively you can use
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 ) { //your section $wp_customize->add_section( 'theme_slug_customizer_your_section', array( 'title' => esc_html__( 'Your Section', 'theme_slug' ), 'priority' => 150 ) ); //radio box sanitization function function theme_slug_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( '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 ) { //your section $wp_customize->add_section( 'theme_slug_customizer_your_section', array( 'title' => esc_html__( 'Your Section', 'theme_slug' ), 'priority' => 150 ) ); //checkbox sanitization function function theme_slug_sanitize_checkbox( $input ){ //returns true if checkbox is checked return ( isset( $input ) ? true : false ); } //add setting to your section $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 ) { //your section $wp_customize->add_section( 'theme_slug_customizer_your_section', array( 'title' => esc_html__( 'Your Section', 'theme_slug' ), 'priority' => 150 ) ); //select sanitization function function theme_slug_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( '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 callwp_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 ) { //your section $wp_customize->add_section( 'theme_slug_customizer_your_section', array( 'title' => esc_html__( 'Your Section', 'theme_slug' ), 'priority' => 150 ) ); //add setting to your section $wp_customize->add_setting( 'theme_slug_customizer_text', array( 'sanitize_callback' => 'wp_filter_nohtml_kses' //removes all HTML from content ) ); $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 ) { //your section $wp_customize->add_section( 'theme_slug_customizer_your_section', array( 'title' => esc_html__( 'Your Section', 'theme_slug' ), 'priority' => 150 ) ); //add setting to your section $wp_customize->add_setting( 'theme_slug_customizer_email', array( 'sanitize_callback' => 'sanitize_email' //removes all invalid characters ) ); $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 ) { //your section $wp_customize->add_section( 'theme_slug_customizer_your_section', array( 'title' => esc_html__( 'Your Section', 'theme_slug' ), 'priority' => 150 ) ); //add setting to your section $wp_customize->add_setting( 'theme_slug_customizer_url', array( 'sanitize_callback' => 'esc_url_raw' //cleans URL from all invalid characters ) ); $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 ) { //your section $wp_customize->add_section( 'theme_slug_customizer_your_section', array( 'title' => esc_html__( 'Your Section', 'theme_slug' ), 'priority' => 150 ) ); //add setting to your section $wp_customize->add_setting( 'theme_slug_customizer_number', array( 'sanitize_callback' => 'absint' //converts value to a non-negative integer ) ); $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 ) { //your section $wp_customize->add_section( 'theme_slug_customizer_your_section', array( 'title' => esc_html__( 'Your Section', 'theme_slug' ), 'priority' => 150 ) ); //add setting to your section $wp_customize->add_setting( 'theme_slug_customizer_dropdown_pages', array( 'sanitize_callback' => 'absint' //input value is a page ID so it must be a positive integer ) ); $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 ) { //your section $wp_customize->add_section( 'theme_slug_customizer_your_section', array( 'title' => esc_html__( 'Your Section', 'theme_slug' ), 'priority' => 150 ) ); //file input sanitization function function theme_slug_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( '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 ) { //your section $wp_customize->add_section( 'theme_slug_customizer_your_section', array( 'title' => esc_html__( 'Your Section', 'theme_slug' ), 'priority' => 150 ) ); //add setting to your section $wp_customize->add_setting( 'theme_slug_customizer_css', array( 'sanitize_callback' => 'wp_strip_all_tags' //strip all HTML tags including script and style ) ); $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 ) { //your section $wp_customize->add_section( 'theme_slug_customizer_your_section', array( 'title' => esc_html__( 'Your Section', 'theme_slug' ), 'priority' => 150 ) ); //add setting to your section $wp_customize->add_setting( 'theme_slug_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, '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
Usewp_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 ) { //your section $wp_customize->add_section( 'theme_slug_customizer_your_section', array( 'title' => esc_html__( 'Your Section', 'theme_slug' ), 'priority' => 150 ) ); //add setting to your section $wp_customize->add_setting( 'theme_slug_customizer_html_code', array( 'sanitize_callback' => 'wp_kses_post' //keeps only HTML tags that are allowed in post content ) ); $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' ); |
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 usingbase64_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 ) { //your section $wp_customize->add_section( 'theme_slug_customizer_your_section', array( 'title' => esc_html__( 'Your Section', 'theme_slug' ), 'priority' => 150 ) ); //script input sanitization function function theme_slug_sanitize_js_code($input){ return base64_encode($input); } //output escape function function theme_slug_escape_js_output($input){ return esc_textarea( base64_decode($input) ); } //add setting to your section $wp_customize->add_setting( 'theme_slug_customizer_js_code', array( 'sanitize_callback' => 'theme_slug_sanitize_js_code', //encode for DB insert 'sanitize_js_callback' => 'theme_slug_escape_js_output' //ecape script for the textarea ) ); $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.- 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
- filter_var($variable, $filter) – filters a variable with a specific filter
- strlen() – gets string length, useful for ZIP codes, phone numbers
Không có nhận xét nào:
Đăng nhận xét