unregister_setting() │ WP 2.7.0
Unregister a setting.
Return
null
. Nothing (null).
Usage
unregister_setting( $option_group, $option_name, $deprecated );
$option_group(string) (required)
The settings group name used during registration.
$option_name(string) (required)
The name of the option to unregister.
$deprecated(callable)
Deprecated.
Default: ''
Examples
#1 Suppose we registered an option and now we need to cancel it:
add_action( 'admin_init', 'eg_settings_api_init' );
// Register a new option
function eg_settings_api_init() {
// Add a block of options to the base "Reading" options page
add_settings_section(
'eg_setting_section', // section
'Header for the settings section',
'eg_setting_section_callback_function',
'reading' // page
);
// Add option fields. Specify the name, description,
// function that outputs the html code of the option field.
add_settings_field(
'eg_setting_name',
'Description of the option field',
'eg_setting_callback_function', // you can specify ''
'reading', // page
'eg_setting_section' // section
);
// register the options so that they are saved when we send them
register_setting( 'reading', 'eg_setting_name' );
}
Now, somewhere along the script, we need to cancel the "eg_setting_name" option. Cancel:
unregister_setting( 'reading', 'eg_setting_name' );
Add Your Own Example
Notes
Global. Array. $new_allowed_options
Global. Array. $wp_registered_settings
Changelog
Since 2.7.0
Introduced.
Since 4.7.0
$sanitize_callback was deprecated. The callback from register_setting() now used instead.
Since 5.5.0
$new_whitelist_options was renamed to $new_allowed_options . Please consider writing more inclusive code.
unregister_setting() unregister setting code
WP 6.7.1
function unregister_setting( $option_group, $option_name, $deprecated = '' ) {
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;
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';
}
$pos = false;
if ( isset( $new_allowed_options[ $option_group ] ) ) {
$pos = array_search( $option_name, (array) $new_allowed_options[ $option_group ], true );
}
if ( false !== $pos ) {
unset( $new_allowed_options[ $option_group ][ $pos ] );
}
if ( '' !== $deprecated ) {
_deprecated_argument(
__FUNCTION__,
'4.7.0',
sprintf(
/* translators: 1: $sanitize_callback, 2: register_setting() */
__( '%1$s is deprecated. The callback from %2$s is used instead.' ),
'<code>$sanitize_callback</code>',
'<code>register_setting()</code>'
)
);
remove_filter( "sanitize_option_{$option_name}", $deprecated );
}
if ( isset( $wp_registered_settings[ $option_name ] ) ) {
// Remove the sanitize callback if one was set during registration.
if ( ! empty( $wp_registered_settings[ $option_name ]['sanitize_callback'] ) ) {
remove_filter( "sanitize_option_{$option_name}", $wp_registered_settings[ $option_name ]['sanitize_callback'] );
}
// Remove the default filter if a default was provided during registration.
if ( array_key_exists( 'default', $wp_registered_settings[ $option_name ] ) ) {
remove_filter( "default_option_{$option_name}", 'filter_default_option', 10 );
}
/**
* Fires immediately before the setting is unregistered and after its filters have been removed.
*
* @since 5.5.0
*
* @param string $option_group Setting group.
* @param string $option_name Setting name.
*/
do_action( 'unregister_setting', $option_group, $option_name );
unset( $wp_registered_settings[ $option_name ] );
}
}
Related Functions