Функция 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, которая может содержать объект с двумя строковыми значениями.
Важно помнить
- При регистрации настроек для использования в REST API не забудьте вызывать
register_setting()как для хукаadmin_init, так и дляrest_api_init. - Если вы используете один и тот же
option_groupдля разных настроек, функции очистки для всех этих настроек будут вызваны при сохранении любой из них. - Убедитесь, что ваши функции очистки работают корректно, чтобы избежать проблем с дублированием вызовов.
Заключение
Функция register_setting() — это мощный инструмент для работы с настройками в WordPress. Она позволяет удобно управлять пользовательскими настройками и интегрировать их с REST API. Используйте приведенные примеры, чтобы начать работу с вашими собственными настройками и адаптируйте их под ваши нужды.