register_setting() │ WP 2.7.0
Register a setting and its data.
Return
null
. Nothing.
Usage
register_setting( $option_group, $option_name, $args );
- $option_group(string) (required)
- A settings group name. Should correspond to an allowed option key name.
Default: allowed option key names include 'general', 'discussion', 'media', 'reading', 'writing', and 'options'
- $option_name(string) (required)
- The name of an option to sanitize and save.
- $args(array)
Data used to describe the setting when registered.
Default: array()
-
type(string)
The type of data associated with this setting. Valid values are 'string', 'boolean', 'integer', 'number', 'array', and 'object'.
-
description(string)
A description of the data attached to this setting.
-
sanitize_callback(callable)
A callback function that sanitizes the option's value.
-
show_in_rest(true|false|array)
Whether data associated with this setting should be included in the REST API. When registering complex settings, this argument may optionally be an array with a 'schema' key.
- default(mixed)
Default value when calling get_option().
Notes
- Global. Array. $new_allowed_options
- Global. Array. $wp_registered_settings
Changelog
Since 2.7.0 |
Introduced. |
Since 3.0.0 |
The misc option group was deprecated. |
Since 3.5.0 |
The privacy option group was deprecated. |
Since 4.7.0 |
$args can be passed to set flags on the setting, similar to register_meta(). |
Since 5.5.0 |
$new_whitelist_options was renamed to $new_allowed_options. Please consider writing more inclusive code. |
Code of register_setting() register setting
WP 5.9.3
function register_setting( $option_group, $option_name, $args = array() ) {
global $new_allowed_options, $wp_registered_settings;
/*
* In 5.5.0, the `$new_whitelist_options` global variable was renamed to `$new_allowed_options`.
* Please consider writing more inclusive code.
*/
$GLOBALS['new_whitelist_options'] = &$new_allowed_options;
$defaults = array(
'type' => 'string',
'group' => $option_group,
'description' => '',
'sanitize_callback' => null,
'show_in_rest' => false,
);
// Back-compat: old sanitize callback is added.
if ( is_callable( $args ) ) {
$args = array(
'sanitize_callback' => $args,
);
}
/**
* Filters the registration arguments when registering a setting.
*
* @since 4.7.0
*
* @param array $args Array of setting registration arguments.
* @param array $defaults Array of default arguments.
* @param string $option_group Setting group.
* @param string $option_name Setting name.
*/
$args = apply_filters( 'register_setting_args', $args, $defaults, $option_group, $option_name );
$args = wp_parse_args( $args, $defaults );
// Require an item schema when registering settings with an array type.
if ( false !== $args['show_in_rest'] && 'array' === $args['type'] && ( ! is_array( $args['show_in_rest'] ) || ! isset( $args['show_in_rest']['schema']['items'] ) ) ) {
_doing_it_wrong( __FUNCTION__, __( 'When registering an "array" setting to show in the REST API, you must specify the schema for each array item in "show_in_rest.schema.items".' ), '5.4.0' );
}
if ( ! is_array( $wp_registered_settings ) ) {
$wp_registered_settings = array();
}
if ( 'misc' === $option_group ) {
_deprecated_argument(
__FUNCTION__,
'3.0.0',
sprintf(
/* translators: %s: misc */
__( 'The "%s" options group has been removed. Use another settings group.' ),
'misc'
)
);
$option_group = 'general';
}
if ( 'privacy' === $option_group ) {
_deprecated_argument(
__FUNCTION__,
'3.5.0',
sprintf(
/* translators: %s: privacy */
__( 'The "%s" options group has been removed. Use another settings group.' ),
'privacy'
)
);
$option_group = 'reading';
}
$new_allowed_options[ $option_group ][] = $option_name;
if ( ! empty( $args['sanitize_callback'] ) ) {
add_filter( "sanitize_option_{$option_name}", $args['sanitize_callback'] );
}
if ( array_key_exists( 'default', $args ) ) {
add_filter( "default_option_{$option_name}", 'filter_default_option', 10, 3 );
}
/**
* Fires immediately before the setting is registered but after its filters are in place.
*
* @since 5.5.0
*
* @param string $option_group Setting group.
* @param string $option_name Setting name.
* @param array $args Array of setting registration arguments.
*/
do_action( 'register_setting', $option_group, $option_name, $args );
$wp_registered_settings[ $option_name ] = $args;
}
Related Functions