register_setting() WP 2.7
Регистрирует новую опцию и callback функцию (функцию обратного вызова) для обработки значения опции при её сохранении в БД.
Используется в связке с другими функциями API настроек:
Они упрощают создание страницы настроек.
Функция также может использоваться для регистрации новой опции, которая будет добавлена на базовую страницу настроек WordPress (Общие, Медиафайлы, Чтение...). Опция добавляется в существующую секцию при помощи функции add_settings_field() или можно создать новую секцию функцией add_settings_section() и добавить опцию туда.
Хуки из функции
Возвращает
null. Ничего не возвращает.
Использование
register_setting( $option_group, $option_name, $args );
- $option_group(строка) (обязательный)
- Название группы, к которой будет принадлежать опция. Это название должно совпадать с названием группы в функции settings_fields().
По умолчанию: нет - $option_name(строка) (обязательный)
- Название опции, которая будет сохраняться в БД.
По умолчанию: нет - $args(массив/строка)
Данные регистрируемой опции (с версии 4.7).
До версии 4.7. тут указывалась коллбэк функция: sanitize_callback, т.е. нужно было указывать строку - название функции, а теперь эта строка указывается в одноименном элементе массива. Прошлый вариант поддерживается, т.е. есть обратная совместимость.
$defaults = array( 'type' => 'string', 'group' => $option_group, 'description' => '', 'sanitize_callback' => null, 'show_in_rest' => false, );
-
sanitize_callback(строка/массив)
Название функции обратного вызова, которая будет обрабатывать значение опции перед сохранением.
Важно! Функция получит один параметр - значение опции. Значение которое указанная функция вернет, будет записано в опцию. -
type(строка)
Тип данных с которыми опция ассоциирована. -
description(строка)
Описание данных, которые будут храниться в этой опции. -
show_in_rest(логический)
Нужно ли добавлять данные этой опции в REST API. - default(разное)
Значение по умолчанию при вызове get_option().
По умолчанию: array()
-
Примеры
#1. Пример показывающий как нужно подключать функцию через хук admin_init:
add_action( 'admin_init', 'register_my_setting' ); function register_my_setting() { register_setting( 'my_options_group', 'my_option_name', 'intval' ); }
#2. Другие примеры
Еще примеры смотрите в описании API опций.
Заметки
#1. Если данные проходят через функцию обработки 2 раза
Например, эта функция вернет строку с двумя восклицательными знаками:
function append_exclamation ($input) { return $input.'!'; }
В этом случае, скорее всего, опции еще не существует в таблице wp_options, поэтому функция update_option() "увидев", что такой опции нет, вызывает add_option(), чтобы добавить новую опцию. Проблема в том, что хук sanitize_option вызывается до вызова функции add_option() и срабатывает второй раз, уже внутри add_option().
#2. Ошибка: ERROR: options page not found - объяснение и решение проблемы:
Такая ошибка возникает, когда фильтр whitelist_options
ничего не знает о вашей новой опции.
register_settings() добавляет данные в глобальную переменную $new_allowed_options. Затем эта переменная объединяется с переменной $whitelist_options в option_update_filter(), которая в свою очередь добавляет новые данные в $new_allowed_options, где $option_group - используется как индекс новых данных. Когда вы получаете ошибку "ERROR: options page not found" - это означает, что не удалось найти опции по ключу.
До версии 5.5 опция $new_allowed_options называлась $new_whitelist_options.
Путаница получается, потому что первый аргумент $options_group используется как ключ, а реальное сравнение в файле options.php происходит с параметром $options_page, который равен $hook_suffix, получаемый из результата работы функции add_submenu_page().
Простое решение этой проблемы, указывать одинаковые названия для параметров $option_group и $option_name.
Другая причина этой ошибки - когда неправильно указан параметр $page при вызове функции:
add_settings_section( $id, $title, $callback, $page )
или
add_settings_field( $id, $title, $callback, $page, $section, $args )
Заметка: $page должен быть равен $menu_slug из функции:
add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $function );
Заметки
- Global. Массив. $new_allowed_options
- Global. Массив. $wp_registered_settings
Список изменений
С версии 2.7.0 | Введена. |
С версии 4.7.0 | $args can be passed to set flags on the setting, similar to register_meta(). |
С версии 5.5.0 | $new_whitelist_options was renamed to $new_allowed_options. Please consider writing more inclusive code. |