register_setting( string $option_group, string $option_name, array $args = array() )
Registers a setting and its data.
Parameters
- $option_group
-
(Required) A settings group name. Should correspond to an allowed option key name.<br> Default allowed option key names include 'general', 'discussion', 'media', 'reading', 'writing', and 'options'.
- $option_name
-
(Required) The name of an option to sanitize and save.
- $args
-
(Optional) Data used to describe the setting when registered.<br>
- 'type'
(string) The type of data associated with this setting.<br> Valid values are 'string', 'boolean', 'integer', 'number', 'array', and 'object'.<br> - 'description'
(string) A description of the data attached to this setting.<br> - 'sanitize_callback'
(callable) A callback function that sanitizes the option's value.<br> - 'show_in_rest'
(bool|array) Whether data associated with this setting should be included in the REST API.<br> When registering complex settings, this argument may optionally be an array with a 'schema' key.<br> - 'default'
(mixed) Default value when callingget_option()
.<br>
Default value: array()
- 'type'
Source
File: wp-includes/option.php
function register_setting( $option_group, $option_name, $args = array() ) {
global $new_whitelist_options, $wp_registered_settings;
$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 WP-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 );
if ( ! is_array( $wp_registered_settings ) ) {
$wp_registered_settings = array();
}
if ( 'misc' == $option_group ) {
_deprecated_argument( __FUNCTION__, 'WP-3.0.0',
/* translators: %s: misc */
sprintf( __( 'The "%s" options group has been removed. Use another settings group.' ),
'misc'
)
);
$option_group = 'general';
}
if ( 'privacy' == $option_group ) {
_deprecated_argument( __FUNCTION__, 'WP-3.5.0',
/* translators: %s: privacy */
sprintf( __( 'The "%s" options group has been removed. Use another settings group.' ),
'privacy'
)
);
$option_group = 'reading';
}
$new_whitelist_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 );
}
$wp_registered_settings[ $option_name ] = $args;
}
Changelog
Version | Description |
---|---|
5.5.0 | $new_whitelist_options was renamed to $new_allowed_options .<br> Please consider writing more inclusive code. |
4.7.0 | $args can be passed to set flags on the setting, similar to register_meta() . |
3.5.0 | The privacy option group was deprecated. |
3.0.0 | The misc option group was deprecated. |
2.7.0 | Introduced. |