Функция register_setting() в WordPress

Введение

Функция register_setting() позволяет зарегистрировать новую опцию и указать функцию обратного вызова, которая будет обрабатывать значение этой опции при сохранении в базе данных. Эта функция может использоваться для добавления новой опции на странице настроек WordPress и в REST API.

Как работает register_setting()

Ваша опция будет добавлена в существующий раздел с помощью функции add_settings_field(), или вы можете создать новый раздел с помощью add_settings_section().

Функцию register_setting() следует вызывать в следующих хуках:

• admin_init — для использования через админскую панель.
• rest_api_init — для использо��ания в REST API. При этом необходимо указать параметр show_in_rest=true.

Важно: При добавлении опции в базу данных функция sanitize_callback может быть вызвана дважды.

Пример функции, которая добавляет два восклицательных знака к строке:

function append_exclamation( $input ){ 
    return $input .'!'; 
}

Когда данная опция добавляется в таблицу wp_options, функция update_option() вызывает add_option() для добавления новой опции (поскольку опция еще не существует).

Ошибка: страница опций не найдена

Эта ошибка возникает, когда фильтр whitelist_options не знает о вашей новой опции.

register_settings() добавляет данные в глобальную переменную $new_allowed_options, которая затем комбинируется с переменной $whitelist_options в функции option_update_filter(). Если вы получаете ошибку "ERROR: options page not found", это означает, что WordPress не может найти опции по ключу.

Решение проблемы

Чтобы избежать этой ошибки, убедитесь, что имена параметров $option_group и $option_name совпадают. Также проверьте правильность параметра $page в вызовах функций add_settings_section($id, $title, $callback, $page) и add_settings_field($id, $title, $callback, $page, $section, $args).

Как использовать register_setting()

Синтаксис

register_setting( $option_group, $option_name, $args );

• $option_group (string) (обязательный): Имя группы, к которой будет принадлежать опция. Это имя должно совпадать с именем группы в settings_fields().
• $option_name (string) (обязательный): Имя опции, которая будет храниться в базе данных.
• $args (array|string): Данные зарегистрированной опции.

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

Пример того, как подключить функцию через хук admin_init:

add_action( 'admin_init', 'register_my_setting' );

function register_my_setting() {
    register_setting( 'my_options_group', 'my_option_name', 'intval' ); 
} 

Если вы хотите зарегистрировать опцию для использования в REST API, вам нужно вызвать функцию и в хуке rest_api_init:

add_action( 'admin_init', 'register_my_setting' );
add_action( 'rest_api_init', 'register_my_setting' );

function register_my_setting() {
    $args = array(
        'sanitize_callback' => 'sanitize_text_field',
        'default' => '',
        'type' => 'string',
        'show_in_rest' => true,
    );

    register_setting( 'my_options_group', 'my_option_name', $args ); 
}

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

Регистрация опции для REST API только

add_action( 'rest_api_init', 'register_block_core_site_logo_setting', 10 );

function register_block_core_site_logo_setting() {
    register_setting( 'general', 'site_logo', [
        'show_in_rest' => array(
            'name' => 'site_logo',
        ),
        'type' => 'integer',
        'description' => __( 'Site logo.' ),
    ]);
}

Регистрация опции типа "массив" в REST API

add_action( 'admin_init', 'wpdocs_foo_register_settings' );
add_action( 'rest_api_init', 'wpdocs_foo_register_settings' );

function wpdocs_foo_register_settings() {
    register_setting( 'general_setting', 'slider-data', array(
        'show_in_rest' => array(
            'name' => 'images_slide',
            'schema' => array(
                'type' => 'array',
                'items' => array(
                    'id' => 'string',
                    'order' => 'string',
                ),
            ),
        ),
        'type' => 'array',
        'sanitize_callback' => 'wpdocs_admin_post_save_data',
    ));
}

Обработка вызова sanitize дважды

При первом добавлении опции в базу данных функция sanitize_callback может вызываться дважды. Если это критично для производительности, обработайте это отдельно:

add_action( 'admin_init', 'on_admin_init' );

function on_admin_init(): void {
    register_setting( PLUGIN_SLUG, PLUGIN_SLUG, [ 'sanitize_callback' => 'my_sanitize_settings' ] ); 
}

function my_sanitize_settings( $input = NULL ): void {
    static $pass_count = 0; 
    $pass_count++;

    if ( $pass_count <= 1 ) {
        // Ваш код для обработки при первом вызове
    }

    // Код обычной очистки
}

Заключение

Функция register_setting() — мощный инструмент, который позволяет управлять опциями в WordPress как в админской панели, так и в REST API. Следуя приведенным рекомендациям и примерам, вы сможете эффективно использовать эту функцию для своих нужд.