register_setting() – регистрирует опцию - Блог про веб-разработку, SEO и маркетинг

Функция регистрирует опцию, которую впоследствии можно вывести на страницах настроек при помощи функции add_settings_field().

По сути помогает предопределить поведение опции, например задав функцию для очистки значений и значение по умолчанию.

register_setting( $option_group, $option_name, $args = array() )

Параметры

$option_group

(строка) Этим параметром определяется, где конкретно отображается поле данной опции.

Например для кастомных страниц настроек он должен совпадать со значением единственного параметра функции settings_fields().

Если опция добавляется на одну из стандартных страниц настроек в WordPress, то значение этого параметра может быть general, discussion, media, reading, writing, misc, options или privacy, пример.

$option_name

(строка) Название опции, то, как она будет храниться в базе данных, в таблице wp_options.

$args

Дополнительные параметры, описывающие поведение этой опции.

sanitize_callback: (строка|массив) Функция или метод для очистки значения этой опции. Функция или метод должны получать и возвращать один аргумент – значение опции, но понятно, что возвращаться должно уже очищенное значение.

К примеру мы можем передать сюда absint, если значения нашей опции только неотрицательные целые числа и мы хотим использовать стандартную функцию WordPress absint() для их очистки.
default: Сюда можно передать значение данной опции по умолчанию, которое будет возвращаться функцией get_option() или в REST API, если данная опция не задана.
show_in_rest: (строка|массив) Должны ли данные из этой опции отображаться в REST API.

По умолчанию – false.
type: (строка) Тип данных значений этой опции. Может принимать значения string, boolean, integer, number, array или object.

Обратите внимание, что если значение параметра show_in_rest установлено в значение false, то и этот параметр использовать не нужно! Потому что он используется только REST API для определения схемы данных и проведения соответствующей очистки.

Для страниц же настроек не имеет никакого эффекта. Ради прикола можете даже зарегистрировать опцию с типом данных boolean и создать текстовое поле под неё – значение прекрасно сохранится в базу данных в виде строки, но со стороны REST API конечно же возникнут вопросики.
description: (строка) И этот параметр также используется только REST API, так что если у вас show_in_rest установлено в значение false или не задано вовсе, то и этот параметр можно смело скипать.

sanitize_callback: (строка|массив) Функция или метод для очистки значения этой опции. Функция или метод должны получать и возвращать один аргумент – значение опции, но понятно, что возвращаться должно уже очищенное значение.

К примеру мы можем передать сюда absint, если значения нашей опции только неотрицательные целые числа и мы хотим использовать стандартную функцию WordPress absint() для их очистки.
default: Сюда можно передать значение данной опции по умолчанию, которое будет возвращаться функцией get_option() или в REST API, если данная опция не задана.
show_in_rest: (строка|массив) Должны ли данные из этой опции отображаться в REST API.

По умолчанию – false.
type: (строка) Тип данных значений этой опции. Может принимать значения string, boolean, integer, number, array или object.

Обратите внимание, что если значение параметра show_in_rest установлено в значение false, то и этот параметр использовать не нужно! Потому что он используется только REST API для определения схемы данных и проведения соответствующей очистки.

Для страниц же настроек не имеет никакого эффекта. Ради прикола можете даже зарегистрировать опцию с типом данных boolean и создать текстовое поле под неё – значение прекрасно сохранится в базу данных в виде строки, но со стороны REST API конечно же возникнут вопросики.
description: (строка) И этот параметр также используется только REST API, так что если у вас show_in_rest установлено в значение false или не задано вовсе, то и этот параметр можно смело скипать.

Примеры

1. Регистрация опции

Основы основ, которые важно знать при использовании register_setting() – это то, что она должна использоваться внутри хука admin_init и в совокупности с функцией add_settings_field() и её второй параметр $option_name должен совпадать с первым параметром функции add_settings_field(). И параметр $option_group у обоих функций также должен совпадать.

add_action( 'admin_init', 'true_simple_setting' );
 
function true_simple_setting() {
 
	// специально вынес эти два параметра в отдельные переменные, чтобы вам было понятно
	$option_name = 'true_option';
	$option_group = 'true_option_group';
 
	add_settings_section( 'true_section', 'Заголовок секции', '', $option_group );
 
	register_setting( $option_group, $option_name, array( 'sanitize_callback' => 'absint' ) );
	add_settings_field( $option_name, 'Заголовок поля', 'field_callback', $option_group, 'true_section', array( 'name' => $option_name ) );
 
}
 
// вывод HTML поля
function field_callback( $args ) {
 
	printf(
		'<input type="number" min="0" name="%s" value="%d" />',
		esc_attr( $args[ 'name' ] ),
		get_option( $args[ 'name' ] )
	);
 
}

Добавлю ещё пару слов в отношении очистки, чтобы вам было понятно на 100%. На 20-й строчке вы можете заметить, что мы использовали поле <input type="number"> со значением атрибута min равным 0, что автоматически подразумевает, что все значения опции – неотрицательные целые числа, а это значит, что идеальная функция очистки для нас – это стандартная функция WordPress absint(), которую я и указал на 11-й строчке.

И небольшое дополнение, что если вы планируете использовать вашу опцию в REST API, то помимо хука admin_init вам ещё понадобится rest_api_init.

add_action( 'admin_init', 'true_simple_setting' );
add_action( 'rest_api_init', 'true_simple_setting' );

2. Произвольная очистка

Пока что мы только очищали неотрицательные целые числа – что может быть скучнее. Предлагаю сделать кое-что поинтереснее. Добавим поле с лицензионным ключом со значением ЛицензионныйКлюч123, которое в админке будет отображаться как *****зионныйКлюч123. Безусловно, тут придётся поработать не только с опцией очистки, но и с колбэк-функцией вывода поля.

Итак, шаг 1, при регистрации опции мы указываем произвольную функцию очистки.

register_setting( 'true_settings', 'license_key', array( 'sanitize_callback' => 'true_sanitize_license' ) );

Шаг 2, напишем функцию очистки лицензионного ключа.

function true_sanitize_license( $value ) {
	// если значение лицензионного ключа начинается с 5 звёздочек
	if( "*****" === substr( $value, 0, 5 ) ) {
		// получаем и возвращаем текущее значение из базы данных
		$value = get_option( 'license_key' );
	} else {
		// очищаем как обычную строку
		$value = sanitize_text_field( $value );
	}
	return $valie
}

И шаг 3, нужно учесть это при выводе поля.

function field_callback( $args ) {
 
	if( $value = get_option( $args[ 'name' ] ) ) {
		$value = '*****' . substr( $value, 5 );
	}
	printf(
		'<input type="text" name="%s" value="%s" />',
		esc_attr( $args[ 'name' ] ),
		$value
	);
 
}

Хуки внутри функции

Да, в этой функции есть один фильтр и один экшен-хук. Сейчас мы о них поговорим. Про хуки кстати у меня есть отдельное руководство.

register_setting_args

$args = apply_filters( 'register_setting_args', $args, $defaults, $option_group, $option_name );

Данный хук позволяет модифицировать параметры $args, про которые мы говорили выше. Например мы легко можем изменить значение по умолчанию на другое, если оно равно какому-то определённому.

add_filter( 'register_setting_args', 'true_modify_defaults', 25, 4);
 
function true_modify_defaults( $args, $defaults, $option_group, $option_name ) {
	if( 'привет' === $args[ 'default' ] && 'true_option' === $option_name ) {
		$args[ 'default' ] = 'пока';
	}
	return $args;
}