unregister_setting() │ WP 2.7.0

Позволяет отменить зарегистрированные ранее настройки (опции). Чаще всего используется с функцией деактивации плагина: register_deactivation_hook().

unregister_setting() - одна из функций API настроек.

Хуки из функции

Возвращает

null. Ничего не возвращает.

Использование

unregister_setting( $option_group, $option_name, $deprecated );
$option_group(строка) (обязательный)
Название группы к которой принадлежит опция. Указывается при регистрации в параметре $option_group в
register_setting( $option_group, $option_name, $sanitize_callback ).
$option_name(строка) (обязательный)
Название опции, которую нужно отменить.
$deprecated(строка)

Запрещен с версии 4.7. Теперь используется callback из функции register_setting().

Название функции, которая обрабатывает значение опции перед сохранением.
По умолчанию: ''

Примеры

0

#1 Предположим мы зарегистрировали опцию и теперь нам нужно её отменить: 

// Регистрация новой опции
function eg_settings_api_init() {  
	// Добавляем блок опций на базовую страницу опций "Чтение"  
	add_settings_section(  
		'eg_setting_section', // секция  
		'Заголовок для секции настроек',  
		'eg_setting_section_callback_function',  
		'reading' // страница  
	);  

	// Добавляем поля опций. Указываем название, описание,   
	// функцию выводящую html код поля опции.  
	add_settings_field(  
		'eg_setting_name',  
		'Описание поля опции',  
		'eg_setting_callback_function', // можно указать ''  
		'reading', // страница  
		'eg_setting_section' // секция  
	); 

	// Регистрируем опции, чтобы они сохранялись при отправке     
	register_setting( 'reading', 'eg_setting_name' );  
}  
add_action( 'admin_init', 'eg_settings_api_init' );  

...

// Теперь, где-то дальше по скрипту нам понадобилось отменить опцию "eg_setting_name". Отменяем:
unregister_setting( 'reading', "eg_setting_name" );

Заметки

  • Global. Массив. $new_allowed_options
  • Global. Массив. $wp_registered_settings

Список изменений

С версии 2.7.0 Введена.
С версии 4.7.0 $sanitize_callback was deprecated. The callback from register_setting() now used instead.
С версии 5.5.0 $new_whitelist_options was renamed to $new_allowed_options. Please consider writing more inclusive code.

Код unregister_setting() WP 6.4.1

wp-includes/option.php 
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 ] );
	}
}

API Настроек