Хук register_setting - WordPres Коды и Элементы

Содержание

Описание хука
Примеры использования
Регистрация настроек для группы опций
Установка значения по умолчанию для настройки
Добавление фильтра для обработки значения настройки
Проверка и сохранение значения настройки
Добавление дополнительных аргументов при регистрации настройки
Вопросы и ответы
Как добавить новую настройку с помощью хука register_setting?
Как изменить значение существующей настройки с помощью хука register_setting?
Как удалить настройку с помощью хука register_setting?
Как добавить фильтр для обработки значения настройки перед сохранением с помощью хука register_setting?
Как получить значение определенной настройки с помощью хука register_setting?
Как проверить, существует ли определенная настройка с помощью хука register_setting?
Как изменить порядок отображения настроек с помощью хука register_setting?
Как добавить секцию для группировки настроек с помощью хука register_setting?
Связанные элементы

Описание хука

Хук «register_setting» позволяет определить и зарегистрировать новую настройку в WordPress. Он срабатывает непосредственно перед регистрацией настройки, но после установки ее фильтров.

Этот хук предоставляет возможность изменить параметры регистрации настройки или выполнить дополнительные действия перед ее регистрацией.

Использование

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

Этот код вызывает хук «register_setting» и передает ему следующие параметры:

$option_group (строка) — Группа настроек.
$option_name (строка) — Название настройки.
$args (массив) — Массив аргументов для регистрации настройки.

$option_group (строка) — Группа настроек.
$option_name (строка) — Название настройки.
$args (массив) — Массив аргументов для регистрации настройки.

<?php
/**
 * Регистрация новой настройки.
 *
 * @param string $option_group Группа настроек.
 * @param string $option_name Название настройки.
 * @param array  $args        Массив аргументов для регистрации настройки.
 */
function wpdocs_register_custom_setting( $option_group, $option_name, $args ) {
    // Ваш код для регистрации настройки
}
add_action( 'register_setting', 'wpdocs_register_custom_setting', 10, 3 );

В приведенном выше примере кода определена функция wpdocs_register_custom_setting, которая регистрирует новую настройку. Функция принимает три параметра: $option_group, $option_name и $args. Вы можете использовать эту функцию для определения своей собственной логики регистрации настройки.

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

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


/**
 * Register a setting and its sanitization callback.
 *
 * @param string   $option_group   The name of the option group. Should match the group name used in settings_fields() or do_settings_sections().
 * @param string   $option_name    The name of the option. Should match the name used in the form input field.
 * @param callable $sanitize_callback   The callback function used to sanitize the option's value.
 */
register_setting( 'general', 'my_option', 'sanitize_callback' );

В этом примере мы регистрируем настройку с именем «my_option» для группы опций «general». Мы также указываем функцию «sanitize_callback», которая будет использоваться для санитизации значения настройки.

Установка значения по умолчанию для настройки


/**
 * Set the default value for a setting.
 *
 * @param string $option_group   The name of the option group. Should match the group name used in settings_fields() or do_settings_sections().
 * @param string $option_name    The name of the option. Should match the name used in the form input field.
 * @param mixed  $default        The default value for the setting.
 */
register_setting( 'general', 'my_option', 'sanitize_callback' );
add_option( 'my_option', 'default_value' );

В этом примере мы устанавливаем значение по умолчанию для настройки «my_option» в группе опций «general». Мы используем функцию «add_option» для установки значения «default_value» в качестве значения по умолчанию.

Добавление фильтра для обработки значения настройки


/**
 * Filter the value of a setting before it is saved.
 *
 * @param mixed  $value          The value of the setting.
 * @param string $option_name    The name of the option.
 * @param string $option_group   The name of the option group.
 * @return mixed                 The filtered value of the setting.
 */
function my_custom_filter( $value, $option_name, $option_group ) {
    // Perform custom filtering here.
    return $filtered_value;
}
add_filter( 'sanitize_option_my_option', 'my_custom_filter', 10, 3 );

В этом примере мы добавляем фильтр «sanitize_option_my_option», который будет вызываться перед сохранением значения настройки «my_option». Внутри функции «my_custom_filter» мы можем выполнять любую необходимую обработку значения и возвращать отфильтрованное значение.

Проверка и сохранение значения настройки


/**
 * Save the value of a setting.
 *
 * @param string $option_group   The name of the option group.
 * @param string $option_name    The name of the option.
 */
function save_my_option( $option_group, $option_name ) {
    if ( isset( $_POST[ $option_name ] ) ) {
        update_option( $option_name, $_POST[ $option_name ] );
    }
}
add_action( 'admin_init', 'save_my_option', 10, 2 );

В этом примере мы добавляем действие «admin_init», которое будет вызываться при инициализации административной части сайта. Внутри функции «save_my_option» мы проверяем, было ли отправлено значение настройки «my_option» через POST-запрос, и если да, то сохраняем его с помощью функции «update_option».

Добавление дополнительных аргументов при регистрации настройки


/**
 * Register a setting with additional arguments.
 *
 * @param string   $option_group   The name of the option group.
 * @param string   $option_name    The name of the option.
 * @param callable $sanitize_callback   The callback function used to sanitize the option's value.
 * @param array    $args           Additional arguments for the setting registration.
 */
register_setting( 'general', 'my_option', 'sanitize_callback', array( 'type' => 'string', 'default' => 'default_value' ) );

В этом примере мы регистрируем настройку «my_option» для группы опций «general» с использованием функции «sanitize_callback» для санитизации значения. Мы также передаем дополнительные аргументы в виде массива, в котором указываем тип настройки («string») и значение по умолчанию («default_value»).

Вопросы и ответы

Как добавить новую настройку с помощью хука register_setting?

Для добавления новой настройки с помощью хука register_setting необходимо вызвать функцию register_setting() и передать ей следующие параметры:

$option_group — строка, указывающая группу настроек, к которой будет принадлежать новая настройка.
$option_name — строка, указывающая имя новой настройки.
$args — массив с аргументами регистрации настройки.

После вызова функции register_setting() будет сгенерирован хук register_setting, который сработает перед регистрацией настройки.


function my_custom_settings() {
  // Регистрация новой настройки
  register_setting( 'my_settings_group', 'my_setting_name', array(
    'type' => 'string',
    'sanitize_callback' => 'sanitize_text_field'
  ) );
}
add_action( 'admin_init', 'my_custom_settings' );

Как изменить значение существующей настройки с помощью хука register_setting?

Для изменения значения существующей настройки с помощью хука register_setting необходимо использовать фильтр pre_update_option_{$option_name}. Этот фильтр позволяет изменить значение настройки перед сохранением.


function my_custom_setting_value( $value, $option_name ) {
  if ( $option_name === 'my_setting_name' ) {
    // Изменение значения настройки
    $value = 'new_value';
  }
  return $value;
}
add_filter( 'pre_update_option_my_setting_name', 'my_custom_setting_value', 10, 2 );

Как удалить настройку с помощью хука register_setting?

Для удаления настройки с помощью хука register_setting необходимо вызвать функцию unregister_setting() и передать ей параметры $option_group и $option_name.


function my_custom_settings() {
  // Удаление настройки
  unregister_setting( 'my_settings_group', 'my_setting_name' );
}
add_action( 'admin_init', 'my_custom_settings' );

Как добавить фильтр для обработки значения настройки перед сохранением с помощью хука register_setting?

Для добавления фильтра для обработки значения настройки перед сохранением с помощью хука register_setting необходимо использовать функцию add_filter() и передать ей параметры pre_update_option_{$option_name} и функцию-обработчик.


function my_custom_setting_value( $value, $option_name ) {
  if ( $option_name === 'my_setting_name' ) {
    // Обработка значения настройки перед сохранением
    $value = my_custom_sanitization_function( $value );
  }
  return $value;
}
add_filter( 'pre_update_option_my_setting_name', 'my_custom_setting_value', 10, 2 );

Как получить значение определенной настройки с помощью хука register_setting?

Для получения значения определенной настройки с помощью хука register_setting можно использовать функцию get_option(). Эта функция принимает один параметр — имя настройки, и возвращает ее значение.


$option_value = get_option( 'my_setting' );

Как проверить, существует ли определенная настройка с помощью хука register_setting?

Для проверки существования определенной настройки с помощью хука register_setting можно использовать функцию get_option(). Эта функция возвращает значение настройки, если она существует, и false в противном случае.


if ( false !== get_option( 'my_setting' ) ) {
    // Настройка существует
} else {
    // Настройка не существует
}

Как изменить порядок отображения настроек с помощью хука register_setting?

Для изменения порядка отображения настроек с помощью хука register_setting можно использовать аргумент priority при регистрации настройки. Чем меньше значение priority, тем раньше будет отображаться настройка.


add_action( 'admin_init', 'my_register_settings' );
function my_register_settings() {
    register_setting( 'my_settings_group', 'my_setting', array(
        'priority' => 10,
    ) );
}

Как добавить секцию для группировки настроек с помощью хука register_setting?

Для добавления секции для группировки настроек с помощью хука register_setting можно использовать аргумент section при регистрации настройки. Этот аргумент принимает имя секции, в которой будет отображаться настройка.


add_action( 'admin_init', 'my_register_settings' );
function my_register_settings() {
    register_setting( 'my_settings_group', 'my_setting', array(
        'section' => 'my_settings_section',
    ) );
}

Хук register_setting в WordPress позволяет регистрировать настройки и управлять ими. С его помощью можно получать значения определенных настроек, проверять их существование, изменять порядок отображения и добавлять секции для группировки настроек. Этот хук является важным инструментом для WEB-разработчиков WordPress, позволяющим эффективно управлять настройками сайта.

Связанные элементы

Функция add_settings_section(): регистрирует новую секцию на странице настроек.
Функция add_settings_field(): регистрирует новое поле на странице настроек.
Функция settings_fields(): выводит скрытые поля формы для защиты от подделки.
Функция do_settings_sections(): выводит все зарегистрированные секции на странице настроек.
Функция do_settings_fields(): выводит все зарегистрированные поля на странице настроек.