WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/register setting

Contents

Description

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 the default WP settings pages like media or general. 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.

Usage

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

Parameters

$option_group
(string) (required) A settings group name. Must exist prior to the register_setting call. This must match the group name in settings_fields()
Default: None
$option_name
(string) (required) The name of an option to sanitize and save.
Default: None
$sanitize_callback
(callback) (optional) A callback function that sanitizes the option's value.
Default: None

Return Values

(void) 
This function does not return a value.

Example

function register_my_setting() {
	register_setting( 'my_options_group', 'my_option_name', 'intval' ); 
} 
add_action( 'admin_init', 'register_my_setting' );

Notes

  • 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' filter 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.

Change Log

Since: 2.7.0

Source File

register_setting() is located in wp-admin/includes/plugin.php.

Resources

Related

Settings API: register_setting(), unregister_setting(), add_settings_field(), add_settings_section(), add_settings_error(), get_settings_errors(), settings_errors()

See also index of Function Reference and index of Template Tags.