Как создать настройки плагина WordPress: подробное руководство для разработчиков

Если вы разрабатываете плагин для WordPress, создание удобной и функциональной панели настроек — одна из ключевых задач. В этой статье мы подробно рассмотрим, как создать собственные настройки плагина, используя WordPress Settings API. Это позволит вам создавать админ-панели с полями, разделами и валидацией данных, что сделает ваш плагин удобным и профессиональным.

Что такое Settings API и зачем он нужен

Settings API — это встроенный в WordPress интерфейс для создания страниц настроек и управления сохранением опций. Он обеспечивает структуру и безопасность, избавляя от необходимости писать собственную логику сохранения и проверки данных.

Использование Settings API позволяет:

• Автоматически создавать страницы настроек в админке.
• Добавлять поля и разделы с удобным управлением.
• Выполнять валидацию и очистку данных перед сохранением.
• Обеспечивать безопасность через nonce и capability.

Рассмотрим пример создания панели настроек для плагина на примере домена wpcoding.

Создаем базовую структуру настроек плагина

Начнем с добавления страницы настроек в меню админки. Для этого используется хук admin_menu. В функции мы добавим пункт меню и зарегистрируем страницу.

add_action('admin_menu', 'wpcoding_add_admin_menu');
add_action('admin_init', 'wpcoding_settings_init');

function wpcoding_add_admin_menu() {
  add_options_page(
    'Настройки WPCoding',
    'WPCoding',
    'manage_options',
    'wpcoding',
    'wpcoding_options_page'
  );
}

Здесь мы добавили страницу настроек в раздел «Настройки» (Options). Следующий шаг — регистрация настроек и полей.

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

В функции wpcoding_settings_init мы зарегистрируем опции и добавим секции и поля на страницу.

function wpcoding_settings_init() {
  register_setting('wpcoding_settings', 'wpcoding_options', 'wpcoding_options_validate');

  add_settings_section(
    'wpcoding_section_main',
    'Основные настройки',
    'wpcoding_section_main_cb',
    'wpcoding'
  );

  add_settings_field(
    'wpcoding_field_text',
    'Текстовое поле',
    'wpcoding_field_text_cb',
    'wpcoding',
    'wpcoding_section_main'
  );

  add_settings_field(
    'wpcoding_field_checkbox',
    'Флажок',
    'wpcoding_field_checkbox_cb',
    'wpcoding',
    'wpcoding_section_main'
  );
}

Здесь мы зарегистрировали опцию wpcoding_options, добавили секцию и два поля: текстовое и чекбокс.

Колбэки для секции и полей

Теперь создадим функции вывода описания секции и полей.

function wpcoding_section_main_cb() {
  echo '<p>Настройте основные параметры плагина WPCoding здесь.</p>';
}

function wpcoding_field_text_cb() {
  $options = get_option('wpcoding_options');
  $value = isset($options['text']) ? esc_attr($options['text']) : '';
  echo '<input type="text" name="wpcoding_options[text]" value="' . $value . '" />';
}

function wpcoding_field_checkbox_cb() {
  $options = get_option('wpcoding_options');
  $checked = isset($options['checkbox']) && $options['checkbox'] === '1' ? 'checked' : '';
  echo '<input type="checkbox" name="wpcoding_options[checkbox]" value="1" ' . $checked . ' />';
}

Функции выводят поля с текущими значениями опций, используя безопасное экранирование.

Создаем страницу настроек с формой

Теперь выведем страницу настроек с формой, которая будет отправлять данные и сохранять опции.

function wpcoding_options_page() {
  ?>
  <div class="wrap">
    <h1>Настройки WPCoding</h1>
    <form action="options.php" method="post">
      <?php
      settings_fields('wpcoding_settings');
      do_settings_sections('wpcoding');
      submit_button('Сохранить настройки');
      ?>
    </form>
  </div>
  <?php
}

Функции settings_fields и do_settings_sections автоматически выведут скрытые поля безопасности и все зарегистрированные секции и поля.

Валидация и очистка данных

Очень важно проверить и очистить данные перед сохранением. Для этого передаем функцию в register_setting и реализуем ее.

function wpcoding_options_validate($input) {
  $output = array();

  if (isset($input['text'])) {
    $output['text'] = sanitize_text_field($input['text']);
  }

  $output['checkbox'] = isset($input['checkbox']) && $input['checkbox'] === '1' ? '1' : '0';

  return $output;
}

Здесь мы используем sanitize_text_field для очистки текста и проверяем, что чекбокс либо «1», либо «0».

Дополнительные советы и лучшие практики

Используйте capability для безопасности

Обязательно проверяйте права пользователя при добавлении меню. В нашем примере мы указали manage_options, что означает, что настройки видны только администраторам.

Добавьте поддержку мультиязычности

Для поддержки перевода используйте функции __() и _e(), а не просто строки. Например:

add_options_page(
  __('Настройки WPCoding', 'wpcoding'),
  __('WPCoding', 'wpcoding'),
  'manage_options',
  'wpcoding',
  'wpcoding_options_page'
);

Используйте кастомные типы полей

Settings API позволяет добавлять текстовые поля, чекбоксы, селекты и даже сложные поля с помощью кастомных колбэков. Это дает гибкость для создания настроек любой сложности.

Пример расширения: добавление селекта и текстового поля с подсказками

Добавим новый селект и поле с подсказками:

add_settings_field(
  'wpcoding_field_select',
  'Выберите опцию',
  'wpcoding_field_select_cb',
  'wpcoding',
  'wpcoding_section_main'
);

add_settings_field(
  'wpcoding_field_textarea',
  'Описание',
  'wpcoding_field_textarea_cb',
  'wpcoding',
  'wpcoding_section_main'
);

function wpcoding_field_select_cb() {
  $options = get_option('wpcoding_options');
  $value = isset($options['select']) ? $options['select'] : '';
  $choices = array(
    'opt1' => 'Опция 1',
    'opt2' => 'Опция 2',
    'opt3' => 'Опция 3'
  );

  echo '<select name="wpcoding_options[select]">';
  foreach ($choices as $key => $label) {
    $selected = selected($value, $key, false);
    echo "<option value='{$key}' {$selected}>{$label}</option>";
  }
  echo '</select>';
}

function wpcoding_field_textarea_cb() {
  $options = get_option('wpcoding_options');
  $value = isset($options['textarea']) ? esc_textarea($options['textarea']) : '';
  echo '<textarea name="wpcoding_options[textarea]" rows="5" cols="50" placeholder="Введите описание...">' . $value . '</textarea>';
}

Не забудьте добавить обработку и валидацию новых полей в функции wpcoding_options_validate.

Заключение

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

Используйте приведенный код как шаблон для собственных проектов на wpcoding.ru и делайте качественные плагины для WordPress!