При разработке плагинов для WordPress часто возникает необходимость создавать страницу настроек, где пользователь может задать параметры работы плагина. Для этого WordPress предоставляет мощный и удобный инструмент — Settings API. В этой статье мы подробно разберем, как правильно использовать Settings API для создания страницы настроек, добавления полей и сохранения данных.
Что такое Settings API и почему его стоит использовать
Settings API — это программный интерфейс WordPress, позволяющий стандартизировать процесс создания и сохранения пользовательских настроек. Вместо того, чтобы вручную обрабатывать формы и сохранять опции в базе данных, этот API берет на себя:
- генерацию HTML форм;
- валидацию и фильтрацию введенных данных;
- сохранение настроек в таблице
wp_options; - отображение сообщений об успешном сохранении или ошибках.
Использование Settings API упрощает поддержку и расширение плагина, а также обеспечивает совместимость с будущими версиями WordPress.
Создаем базовую структуру для настроек плагина
Рассмотрим пример создания страницы настроек для плагина под доменом wpgen. Предположим, нам нужно добавить три настройки:
- Поле для ввода текстовой строки — «API ключ»;
- Чекбокс для включения или отключения функции — «Включить режим отладки»;
- Выпадающий список с вариантами — «Выбор цвета темы».
Начнем с регистрации страницы настроек в меню WordPress и определения полей.
Регистрация страницы настроек в меню
function wpgen_register_settings_page() {
add_options_page(
'Настройки WPGen',
'WPGen Настройки',
'manage_options',
'wpgen-settings',
'wpgen_render_settings_page'
);
}
add_action('admin_menu', 'wpgen_register_settings_page');Этот код добавляет новый пункт в меню «Настройки» админки WordPress, который открывает нашу страницу настроек.
Регистрация настроек и полей
function wpgen_settings_init() {
// Регистрируем группу настроек
register_setting('wpgen_settings_group', 'wpgen_options', 'wpgen_sanitize_options');
// Добавляем секцию
add_settings_section(
'wpgen_settings_section',
'Основные настройки',
'wpgen_settings_section_callback',
'wpgen-settings'
);
// Поле: API ключ
add_settings_field(
'wpgen_api_key',
'API ключ',
'wpgen_api_key_render',
'wpgen-settings',
'wpgen_settings_section'
);
// Поле: Режим отладки
add_settings_field(
'wpgen_debug_mode',
'Включить режим отладки',
'wpgen_debug_mode_render',
'wpgen-settings',
'wpgen_settings_section'
);
// Поле: Выбор цвета темы
add_settings_field(
'wpgen_theme_color',
'Цвет темы',
'wpgen_theme_color_render',
'wpgen-settings',
'wpgen_settings_section'
);
}
add_action('admin_init', 'wpgen_settings_init');Здесь мы создаем группу настроек, секцию и три поля. Для каждого поля определяем функцию-рендер, которая выведет HTML для поля ввода.
Функции рендера полей и секции
Теперь опишем, как выводить поля на странице настроек.
function wpgen_settings_section_callback() {
echo '<p>Настройте параметры плагина WPGen.</p>';
}
// Рендер поля API ключ
function wpgen_api_key_render() {
$options = get_option('wpgen_options');
?>
<input type="text" name="wpgen_options[api_key]" value="<?php echo esc_attr($options['api_key'] ?? ''); ?>" size="50" />
<?php
}
// Рендер чекбокса отладки
function wpgen_debug_mode_render() {
$options = get_option('wpgen_options');
?>
<input type="checkbox" name="wpgen_options[debug_mode]" value="1" <?php checked(1, $options['debug_mode'] ?? 0); ?> /> Включить режим отладки
<?php
}
// Рендер выпадающего списка цвета темы
function wpgen_theme_color_render() {
$options = get_option('wpgen_options');
$colors = ['light' => 'Светлая', 'dark' => 'Темная', 'blue' => 'Синяя'];
?>
<select name="wpgen_options[theme_color]">
<?php foreach($colors as $value => $label) : ?>
<option value="<?php echo esc_attr($value); ?>" <?php selected($options['theme_color'] ?? '', $value); ?>><?php echo esc_html($label); ?></option>
<?php endforeach; ?>
</select>
<?php
}Вывод страницы настроек
Теперь реализуем функцию, которая выведет HTML страницы с формой настроек.
function wpgen_render_settings_page() {
?>
<div class="wrap">
<h1>Настройки плагина WPGen</h1>
<form action="options.php" method="post">
<?php
settings_fields('wpgen_settings_group');
do_settings_sections('wpgen-settings');
submit_button();
?>
</form>
</div>
<?php
}Санитизация и валидация данных
Для надежной работы важно фильтровать и проверять введённые пользователем данные перед сохранением. Опишем функцию санитизации.
function wpgen_sanitize_options($input) {
$output = [];
if (isset($input['api_key'])) {
$output['api_key'] = sanitize_text_field($input['api_key']);
}
$output['debug_mode'] = !empty($input['debug_mode']) ? 1 : 0;
$allowed_colors = ['light', 'dark', 'blue'];
if (isset($input['theme_color']) && in_array($input['theme_color'], $allowed_colors, true)) {
$output['theme_color'] = $input['theme_color'];
} else {
$output['theme_color'] = 'light';
}
return $output;
}Использование настроек в коде плагина
После того, как настройки созданы и сохранены, вы можете получать их с помощью get_option('wpgen_options') и использовать в работе плагина.
$wpgen_options = get_option('wpgen_options');
if (!empty($wpgen_options['debug_mode'])) {
error_log('WPGen Debug mode is enabled');
}
// Используем API ключ
$api_key = $wpgen_options['api_key'] ?? '';
// Цвет темы
$theme_color = $wpgen_options['theme_color'] ?? 'light';Альтернативные решения и плагины для управления настройками
Если вы предпочитаете не писать настройки вручную, можно использовать плагины, облегчающие работу:
- Clearfy Pro — включает инструменты оптимизации и расширенные настройки;
- WPRemark — удобный редактор и настройщик контента.
Однако для контроля и гибкости лучше использовать Settings API напрямую.