Chip Bennett 3:39 pm on January 30, 2014

Using the Theme Customizer with the Theme Mods API

Several developers are hooking into the awesome Theme CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways., and in many places even replacing traditional Theme Settings pages with the Theme Customizer. This is a great development, but there’s one caveat when using the Theme Mods API (as opposed to the Settings API): you have to be sure to sanitize on input.

With the Settings API, the Theme registers its setting via register_setting(), which accepts a sanitization callback as one of its parameters. When you hook into the Theme Customizer with Settings API-defined options, the user-input option data are automatically passed through the defined sanitization callback. But the Theme Mods API is designed to be much simpler (and generally more user-friendly), and has no analogous method to define a sanitization callback. That means that user-input option data must be explicitly sanitized on input.

Fortunately, the Theme Customizer API provides a way to sanitize Theme Mods option data: the ‘sanitize_callback’ parameter of the add_setting() argument array. Didn’t know about that parameter? Don’t worry; neither did I until recently. It’s so super-secret that it’s not even listed in the add_setting() method Codex entry. Fortunately, Konstantin Obenland discusses it here.

Here’s an example. Let’s say the setting is for a slider speed option. The user is expected to enter an integer (in seconds). Here are typical add_setting() and add_control() method calls:

$wp_customize->add_setting( 'prefix_slider_speed', array( 
	'default' => '5'
) );
		
$wp_customize->add_control( 'prefix_slider_speed', array(
	'label'    => __( 'Animation Speed in Seconds', 'textdomain' ),
	'section'  => 'prefix_slider_section',
	'settings' => 'prefix_slider_speed',
	'type'     => 'text'
) );

See the problem? The user can enter anything into that text field, and WordPress will dutifully add the user-input data into the database, and output it upon request, via get_theme_mod(). What happens if the user inputs the following?

1000" onclick="javascript:alert(1)" data-foo="

(Note: don’t try this at home, kids)

Enter ‘sanitize_callback’:

$wp_customize->add_setting( 'prefix_slider_speed', array( 
	'default' => '5',
	'sanitize_callback' => 'prefix_sanitize_integer'
) );

Once the callback is referenced, you just need to declare it (if it’s a custom function; in many cases, including this one, you could simply pass a coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.-defined sanitization function here and be done):

function prefix_sanitize_integer( $input ) {
	return absint( $input );
}

Now, the saved input is sanitized as an actual integer.

There are several valid sanitization methods; the key here is to ensure that you’re aware of the need to perform sanitization.

P.S. Anyone want to show the Customizer API Codex entries some love? The sanitize_callback parameter isn’t mentioned, and none of the method entries have source references.

Samuel Wood (Otto) 3:54 pm on January 30, 2014

I updated the codex. Added info on the sanitize_js_callback too.

Minor point: You don’t have to use custom functions for every little thing. This would work just fine:

‘sanitize_callback’ => ‘absint’

One way to think of these sorts of things is with the idea of a “filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. function”. In WordPress, a “filter” takes some input, modifies it, and expects to have that input returned afterwards. This pattern is commonplace in PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.php. itself, with all sorts of things. Any of those PHP built-in functions can be used as filter functions without a problem.

For absint, which is a WP function, it’s basically the combination of the PHP functions abs() and intval(). If negative numbers were acceptable, then just using ‘intval’ would work too.
- Chip Bennett 4:41 pm on January 30, 2014
  
  Yep; mentioned that: …if it’s a custom function; in many cases, including this one, you could simply pass a coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.-defined sanitization function here and be done 😉
Samuel Wood (Otto) 4:06 pm on January 30, 2014

Oh, and since HTMLHTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites. colors are commonplace, there’s a few functions for this so you don’t have to reinvent the wheel.

The sanitize_hex_color() function will act as the sanitize callback for anything requiring a hashed color, like #123456.

The sanitize_hex_color_no_hash() function will act as the sanitize callback for anything requiring a non-hashed color, like 123456.

The maybe_hash_hex_color() function will act as the sanitize_js_callback for anything requiring a hashed color. If the value is unhashed, it will hash it for you. This is generally only needed if you’re using sanitize_hex_color_no_hash() to start with, and you want the hashed value in the customizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. and the unhashed value in the database.
- Chip Bennett 4:43 pm on January 30, 2014
  
  Ideally, coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. would define sanitization functions for all common data types, and then sanitize appropriately based on a ‘data_type’ parameter (for either the Theme Mods APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. or the Settings API).
  
  As a good middle-ground, the Data Validation Codex entry could use some freshening up, to list all the core-defined sanitization functions, with code examples. (For example: I never knew about the hex color sanitization functions, until just now.)
  - tskk 4:48 pm on January 30, 2014
    
    I was about to ask if there is a list of coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. defined sanitization functions 🙂
  - Samuel Wood (Otto) 5:40 pm on January 31, 2014
    While there are many functions that can be used, and knowing about them is half the battle (GIJoe!), I’d be careful in any such list of functions to note that in most real-world cases, none of them would be appropriate. Sanitization is about safety, certainly, but it’s also about making sure that the input makes sense.
    
    For example, let’s quickly enumerate the various data types commonly used:
    
    Numbers. These can be integers, floats, negatives, and limited to ranges. Any sanitization function should certainly ensure that the data is a number. You could use intval() or floatval() for that, and if negatives were not allowed, you could use abs() for that. Limiting to a valid range (1-100, say) would require a custom function.
    
    Strings. Strings can obviously take any form, and one should do things like strip_tags on them if HTMLHTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites. is not allowed, or use kses if a limited set of HTML is allowed. But one might want to check for length as well, and things of that nature.
    
    Sets. Checkboxes or radio controls or dropdowns will only have some limited number of choices, and a sanitization function for these should make sure that the input is one of those choices. No built-in function can satisfy that demand.
    
    Specific formats. Like HTML colors. There can be pre-defined functions for some of these, but there cannot be for all of them. Consider a date input, one might want to run the input through strtotime() to make sure that the result is a meaningful date and possibly within a reasonable range.
    
    For most cases, a custom function will be desirable. For safety cases, you can sometimes get away from using a built-in function, but if you want to bulletproof inputs, then you will need custom functions to check not just the safety aspects, but the sanity ones as well, and to have it return default values when the input falls outside of the expected values.
Rizqy Hidayat 1:25 pm on March 27, 2014

Cool, this was what I’m looking for. But for functions like sanitize_hex_color(), sanitize_hex_color_no_hash(), are the any documentation for these? Cause I found nothing when searching in the Codex.
mcunha98 5:36 pm on April 23, 2014

Chip

This is an obligation ?

I had my theme reffused because I don’t use it in “ALL” settings, but for example in colors or in dropdownlists this is totally unnecessary.

I understand that you need to use an sanitize only you need to check the data (an integer, a date, etc…) for free text and previous defined options not, right ?
- Chip Bennett 2:08 pm on April 24, 2014
  
  As a general rule (from the Guidelines), all untrusted data (i.e. all user input – Theme settings, WidgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. settings, custom post metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. data, etc.) must be sanitized on input and escaped on output. The Theme CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. is merely an alternate admin UIUI UI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing. for either the Settings APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. or Theme Mods API, and still requires all input to be sanitized.
  
  If you have questions about sanitization of specific options passed through the Customizer, please ask in the ticket associated with the specific Theme. Either you or the reviewer is welcome to CC an admin to help if needed.