WordPress: использование настроек API

В этой записи пойдет речь о создании собственной страницы с настройками в админ панели WordPress.

Регистрация настроек

Для создания настроек, вам нужно сначала её зарегистрировать используя функцию register_setting(), это создаст их в таблице {$wpdb->prefix}_options.

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

Вы можете добавить новые поля для настроек используя метод add_settings_field().

register_setting() функция, а так же add_settings_*() должны быть добавлены в хук admin_init, чтобы они правильно работали.

Добавление настройки

register_setting( 
    string $option_group, 
    string $option_name, 
    callable $sanitize_callback = ''
);

Для добавления новой настройки используйте register_setting().

Простой вариант её использования:

/**
 * Регистрация настроек.
 */
function bologer_register_my_setting() {
    register_setting( 'my_options_group', 'bologer_option_name', 'intval' ); 
} 
add_action( 'admin_init', 'bologer_register_my_setting' );

Добавление секции

add_settings_section( 
    string $id, 
    string $title, 
    callable $callback, 
    string $page
);

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

Для создания секции используйте add_settings_section(). Пример использования смотрите ниже:

add_settings_section(
    'eg_setting_section',
    __( 'Example settings section in reading', 'bologer' ),
    'wpdocs_setting_section_callback_function',
    'reading'
);
 
/**
 * Settings section display callback.
 *
 * @param array $args Display arguments.
 */
function wpdocs_setting_section_callback_function( $args ) {
    // echo section intro text here
    echo '<p>id: ' . esc_html( $args['id'] ) . '</p>';                         // id: eg_setting_section
    echo '<p>title: ' . apply_filters( 'the_title', $args['title'] ) . '</p>'; // title: Example settings section in reading
    echo '<p>callback: ' . esc_html( $args['callback'] ) . '</p>';             // callback: eg_setting_section_callback_function
}

Добавление поля

add_settings_field(
    string $id, 
    string $title, 
    callable $callback, 
    string $page, 
    string $section = 'default', 
    array $args = []
);

Подробнее о добавлении нового поля, вы можете прочитать в официальной документации WordPress — add_settings_field(), а так же понять как она работает в примере ниже.

Пример

<?php
function bologer_settings_init()
{
    // регистрируем новую настройку для страницы "reading"
    register_setting('reading', 'bologer_setting_name');
 
    // регистрируем новую секцию на странице "reading"
    add_settings_section(
        'bologer_settings_section',
        'Bologer настройки секция',
        'bologer_settings_section_cb',
        'reading'
    );
 
    // регистрируем новое поле для секции "bologer_settings_section" для страницы "reading"
    add_settings_field(
        'wporg_settings_field',
        'WPOrg Setting',
        'bologer_settings_field_cb',
        'reading',
        'bologer_settings_section'
    );
}
 
/**
 * регистрируем bologer_settings_init в хук admin_init
 */
add_action('admin_init', 'bologer_settings_init');
 
/**
 * callback функции
 */
 
// функция для вывода секции
function bologer_settings_section_cb()
{
    echo '<p>Описание секции</p>';
}
 
// функция для вывода поля
function bologer_settings_field_cb()
{
    // get the value of the setting we've registered with register_setting()
    $setting = get_option('bologer_setting_name');
    // выводим само поле
    ?>
    <input type="text" name="bologer_setting_name" value="<?php echo isset( $setting ) ? esc_attr( $setting ) : ''; ?>">
    <?php
}

Получить настройки

get_option(
    string $option,
    mixed $default = false
);

Для получения настроек используйте функцию get_option().

Эта функцию принимает два аргумента: названии опции и стандартное значение для опции (в случае если она будет отсутствовать).

// get the value of the setting we've registered with register_setting()
$setting = get_option('wporg_setting_name');