Функция UNREGISTER_SETTING() │ WP 2.7.0

Функция unregister_setting() используется для отмены регистрации настроек в WordPress.

Что такое unregister_setting?

Эта функция удаляет настройки, которые были ранее зарегистрированы. Например, если вы создали новую настройку и решили, что она больше не нужна, вы можете ее отменить с помощью этой функции.

Возвращаемое значение

Функция unregister_setting() не возвращает ничего (null).

Как использовать unregister_setting

Вот синтаксис вызова этой функции:

unregister_setting( $option_group, $option_name, $deprecated );

• $option_group (строка) (обязательно): имя группы настроек, которое использовалось при регистрации.
• $option_name (строка) (обязательно): имя опции, которую нужно отменить.
• $deprecated (функция): устаревший параметр. По умолчанию равен пустой строке ('').

Примеры использования

Пример 1: Отменяем опцию

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

add_action( 'admin_init', 'eg_settings_api_init' );  

// Регистрация новой опции
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' );  
}  

// Теперь, где-то в коде, мы отменяем опцию "eg_setting_name".
unregister_setting( 'reading', 'eg_setting_name' );

Примечания

• Глобальная переменная: $new_allowed_options
• Глобальная переменная: $wp_registered_settings

Изменения в функции

• С версии 2.7.0: Функция была введена.
• С версии 4.7.0: Параметр $sanitize_callback устарел. Теперь используется коллбек из register_setting().
• С версии 5.5.0: $new_whitelist_options была переименована в $new_allowed_options. Рекомендуется писать более инклюзивный код.

Код функции unregister_setting

Вот как выглядит код функции unregister_setting в WordPress:

function unregister_setting( $option_group, $option_name, $deprecated = '' ) {
global $new_allowed_options, $wp_registered_settings;

// В версии 5.5.0 глобальная переменная была переименована
$GLOBALS['new_whitelist_options'] = &$new_allowed_options;

if ( 'misc' === $option_group ) {
    _deprecated_argument(
        __FUNCTION__,
        '3.0.0',
        sprintf(
            __( 'Группа опций "%s" была удалена. Используйте другую группу настроек.' ),
            'misc'
        )
    );
    $option_group = 'general';
}

if ( 'privacy' === $option_group ) {
    _deprecated_argument(
        __FUNCTION__,
        '3.5.0',
        sprintf(
            __( 'Группа опций "%s" была удалена. Используйте другую группу настроек.' ),
            '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(
            __( '%1$s устарела. Используйте коллбек из %2$s.' ),
            '$sanitize_callback',
            'register_setting()'
        )
    );
    remove_filter( "sanitize_option_{$option_name}", $deprecated );
}

if ( isset( $wp_registered_settings[ $option_name ] ) ) {
    // Убираем обработчик, если он был установлен при регистрации.
    if ( ! empty( $wp_registered_settings[ $option_name ]['sanitize_callback'] ) ) {
        remove_filter( "sanitize_option_{$option_name}", $wp_registered_settings[ $option_name ]['sanitize_callback'] );
    }

    // Убираем фильтр по умолчанию, если он был задан при регистрации.
    if ( array_key_exists( 'default', $wp_registered_settings[ $option_name ] ) ) {
        remove_filter( "default_option_{$option_name}", 'filter_default_option', 10 );
    }

    /**
     * Срабатывает сразу перед отменой настройки и после удаления ее фильтров.
     *
     * @since 5.5.0
     *
     * @param string $option_group Группа настройки.
     * @param string $option_name  Имя настройки.
     */
    do_action( 'unregister_setting', $option_group, $option_name );

    unset( $wp_registered_settings[ $option_name ] );
}

}

Теперь у вас есть полное понимание функции unregister_setting() и примеры её использования. Это поможет вам управлять своими настройками в WordPress более эффективно!