Регистрация Настроек в WordPress с помощью register_setting()

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

register_setting( string $option_group, string $option_name, array $args = array() )

Параметры

• $option_group (string) (обязательный): Название группы настроек, с которой будет связана опция. Например, это может быть general, discussion и т.д.
• $option_name (string) (обязательный): Имя опции, которую нужно сохранить.
• $args (array) (необязательный): Массив параметров, описывающий настройку.

Возможные ключи для $args:

• type (string): Тип данных, связанных с этой настройкой (например, ‘string’, ‘boolean’, ‘integer’, ‘array’, ‘object’).
• label (string): Метка для данных, связанных с этой настройкой.
• description (string): Описание данных, связанных с этой настройкой.
• sanitize_callback (callable): Функция для очистки значения опции перед его сохранением.
• show_in_rest (bool|array): Определяет, должны ли данные, связанные с этой настройкой, включаться в REST API.
• default (mixed): Значение по умолчанию при вызове get_option().

Простой пример

add_action( 'admin_init', 'custom_register_setting' );

function custom_register_setting() {
    register_setting( 'custom_options_group', 'custom_option_name', 'sanitize_text_field' );
}

В этом примере мы регистрируем новую настройку с именем custom_option_name, которая будет храниться в группе custom_options_group и будет очищаться с помощью функции sanitize_text_field.

Пример с использованием $args

add_action( 'admin_init', 'advanced_register_setting' );

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

    register_setting( 'advanced_options_group', 'advanced_option_name', $args );
}

Здесь мы добавляем более сложные параметры: устанавливаем тип данных как string, определяем функцию очистки, задаем значение по умолчанию и указываем, что настройка должна быть доступна в REST API.

Пример с массивом

Если вы хотите сохранить массив в настройках и сделать его доступным через REST API, используйте следующий код:

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

function array_register_setting() {
    register_setting( 'array_options_group', 'my_array_option', array(
        'show_in_rest' => array(
            'schema' => array(
                'type' => 'array',
                'items' => array(
                    'type' => 'string',
                ),
            ),
        ),
        'type' => 'array',
        'sanitize_callback' => 'array_sanitize_callback',
    ));
}

function array_sanitize_callback( $input ) {
    return array_map( 'sanitize_text_field', (array) $input );
}

В этом примере мы регистрируем настройку my_array_option, которая может содержать массив строк. Функция array_sanitize_callback используется для очистки каждого элемента массива.

Пример с объектом

Для регистрации объекта можно использовать следующий код:

add_action( 'admin_init', 'object_register_setting' );

function object_register_setting() {
    register_setting( 'object_options_group', 'my_object_option', array(
        'type' => 'object',
        'default' => array(
            'key1' => 'value1',
            'key2' => 'value2',
        ),
        'show_in_rest' => array(
            'schema' => array(
                'type' => 'object',
                'properties' => array(
                    'key1' => array('type' => 'string'),
                    'key2' => array('type' => 'string'),
                ),
            ),
        ),
    ));
}

В этом примере мы регистрируем настройку my_object_option, которая может содержать объект с двумя строковыми значениями.

Важно помнить

1. При регистрации настроек для использования в REST API не забудьте вызывать register_setting() как для хука admin_init, так и для rest_api_init.
2. Если вы используете один и тот же option_group для разных настроек, функции очистки для всех этих настроек будут вызваны при сохранении любой из них.
3. Убедитесь, что ваши функции очистки работают корректно, чтобы избежать проблем с дублированием вызовов.

Заключение

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