register_setting() │ WP 2.7.0

Регистрирует новую опцию и callback функцию (функцию обратного вызова) для обработки значения опции при её сохранении в БД.

Функция также может использоваться для регистрации новой опции, которая будет добавлена на базовую страницу настроек 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()

Примеры

add_action( 'admin_init', 'register_my_setting' );
function register_my_setting() {
	register_setting( 'my_options_group', 'my_option_name', 'intval' ); 
} 

Добавить свой пример

Заметки

#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" - это означает, что не удалось найти опции по ключу.

Путаница получается, потому что первый аргумент $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 )

add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $function );