register_setting( string $option_group, string $option_name, array $args = array() )
Registers a setting and its data.
Parameters
-
$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 Optional -
Data used to describe the setting when registered.
type
stringThe type of data associated with this setting.
Valid values are'string'
,'boolean'
,'integer'
,'number'
,'array'
, and'object'
.description
stringA description of the data attached to this setting.sanitize_callback
callableA callback function that sanitizes the option's value.show_in_rest
bool|arrayWhether 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
mixedDefault value when callingget_option()
.
Default:
array()
Source
File: wp-includes/option.php
.
View all references
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;
}
Hooks
-
do_action( 'register_setting',
string $option_group ,string $option_name ,array $args ) -
Fires immediately before the setting is registered but after its filters are in place.
-
apply_filters( 'register_setting_args',
array $args ,array $defaults ,string $option_group ,string $option_name ) -
Filters the registration arguments when registering a setting.
Changelog
Version | Description |
---|---|
5.5.0 | $new_whitelist_options was renamed to $new_allowed_options .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. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
Some notes about the elements in the
$args
parameter:'type'
:'show_in_rest'
is set. So if'show_in_rest'
is false or not part of$args
, do not bother with setting a'type'
.'type'
set to"boolean"
. WP will not complain and will store the value in the options table. It would however cause issues with the REST API, so be careful!)'array'
and'object'
.'description'
:'show_in_rest'
is set. So if'show_in_rest'
is false or not part of$args
, do not bother with setting a'description'
.'default'
:get_option()
) and the REST API.In conclusion: if you do not plan to include your setting in the REST API, it is perfectly enough to only set the
'default'
and the'sanitize_callback'
elements in the $args array. Anything else would be ignored anyway.Basic Example
If you plan to use your setting in the REST API, use both the
rest_api_init
andadmin_init
hooks when callingregister_setting()
instead of justadmin_init
. Theshow_in_rest
argument is ineffective when hooked intoadmin_init
alone.The sanitize callback will be launched twice! Therefore, if sanitizing involves any performance critical or singular tasks, then measures must be taken in the callback to avoid duplicate execution of those portions.
Top ↑
Feedback
As pointed out by Andy Schmidt the function defined as sanitize_callback will be launched twice, however – at least according to my tests on v4.9.9 – it is only called twice for the first time the setting is submitted and added to the options table in the database. Subsequent updates to the setting execute the sanitize_callback function only once. So unless you are performing something really-really-really heavy operation to sanitize, there’s no need to worry about it, as any workarounds would only save 1 occasion of call to the function per site per plugin installation. — By Bence Szalai —
If you want the setting to appear in the
wp-json/wp/v2/settings
endpoint, you’ll need to callregister_setting()
on therest_api_init
action, in addition to the normaladmin_init
action.An example of array settings. if you want to save an array in settings and also show the array setting to appear in the
wp-json/wp/v2/settings
endpoint, then you have to register show_in_rest schema.Example for
object
andarray
types: