Register a setting and its sanitization callback.

This is part of the Settings API, which lets you automatically generate wp-admin settings pages by registering your settings and using a few callbacks to control the output.

This function can also be used to register settings that will be shown on some default WP settings pages like "media" or "general". (As of WordPress 4.1 this function does not save settings if added to the "permalink" page.) Once the setting is registered you can add it to an existing section with add_settings_field() or create a new section with add_settings_section() and add it to that.

register_setting() 描述


 <?php register_setting$option_group$option_name$sanitize_callback ); ?> 

register_setting() 用法



(string) (必填) A settings group name. Must exist prior to the register_setting call. This must match the group name in settings_fields()

默认值: None


(string) (必填) The name of an option to sanitize and save.

默认值: None


(callback) (可选) A callback function that sanitizes the option's value.

默认值: None

register_setting() 参数



This function does not return a value.

register_setting() 返回值


  • It seems the data is passed through the sanitize function twice. For example this will give you a string with two exclamation marks: function append_exclamation ($input) { return $input.'!'; }

This should only happen when the option is not yet in the wp_options table. The issue is that the technique used by options.php is to fallback on update_option's ability to detect that an option does not yet exist and subsequently call add_option. Problem being that update_option calls sanitize_option before add_option, which also calls sanitize_option.

  • The "Error: options page not found." problem (including a solution and explanation):

The problem then is, that the 'whitelist_options' 过滤器 hasn't got the right index for your data. It gets applied on options.php#98 (WP 3.4).

register_settings() adds your data to the global $new_whitelist_options. This then gets merged with the global $whitelist_options inside the option_update_filter() (resp. add_option_whitelist()) callback(s). Those callbacks add your data to the global $new_whitelist_options with the $option_group as index. When you encounter "Error: options page not found." it means your index hasn't been recognized. The misleading thing is that the first argument is used as index and named $options_group, when the actual check in options.php#112 happens against $options_page, which is the $hook_suffix, which you get as @return value from add_submenu_page().

In short, an easy solution is to make $option_group match $option_name.

Another cause for this error is having an invalid value for $page parameter when calling either add_settings_section( $id, $title, $callback, $page ) or add_settings_field( $id, $title, $callback, $page, $section, $args ).

Hint: $page should match $menu_slug from Function Reference/add theme page.

  • Make sure that the sanitization callback function input type is consistent with the $option_name type. For example, the absint function wouldn't work properly if $option_name is an array.

register_setting() 注意


添加于 版本: 2.7.0

register_setting() 历史


register_setting() 函数的代码位于 wp-admin/includes/plugin.php.

/* ----------------------------------
 * wordpress之魂 ©
 * ---------------------------------- */
 * Register a setting and its sanitization callback
 * @since 2.7.0
 * @global array $new_whitelist_options
 * @param string $option_group A settings group name. Should correspond to a whitelisted option key name.
 * 	Default whitelisted option key names include "general," "discussion," and "reading," among others.
 * @param string $option_name The name of an option to sanitize and save.
 * @param callable $sanitize_callback A callback function that sanitizes the option's value.
function register_setting( $option_group, $option_name, $sanitize_callback = '' ) {
	global $new_whitelist_options;

	if ( 'misc' == $option_group ) {
		_deprecated_argument( __FUNCTION__, '3.0', sprintf( __( 'The "%s" options group has been removed. Use another settings group.' ), 'misc' ) );
		$option_group = 'general';

	if ( 'privacy' == $option_group ) {
		_deprecated_argument( __FUNCTION__, '3.5', sprintf( __( 'The "%s" options group has been removed. Use another settings group.' ), 'privacy' ) );
		$option_group = 'reading';

	$new_whitelist_options[ $option_group ][] = $option_name;
	if ( $sanitize_callback != '' )
		add_filter( "sanitize_option_{$option_name}", $sanitize_callback );

register_setting() 源文件