add_role() │ WP 2.0.0

Додає нову роль WordPress.

Функція повинна бути викликана лише один раз. Тому що вона змінює дані в базі даних (таблиця wp_options , поле wp_user_roles ). Тому краще змінювати їх під час активації/деактивації плагіна або теми, див.

Коли викликати

Перед тим як додавати або змінювати роль, переконайтеся, що глобальна змінна $wp_roles доступна. Найкраще використовувати хуки активації плагінів або тим, щоб додати нову роль. За хук активації плагіна відповідає функція register_activation_hook() .

Видалення існуючої ролі

Якщо ви створюєте нову роль і вказуєте їй можливості, переконайтеся, що такої ролі не існує. Ця функція не працюватиме якщо роль вже існує в базі даних.

Варіант вирішення такої проблеми перед створенням ролі її можна видалити, використовуючи функцію remove_role() , в якій вказати створювану вами роль.

Працює на основі:
wp_roles() ,
WP_Roles()

Хуків немає.

Повертає

WP_Role|null. WP_Role об’єкт, якщо вдалося додати роль і null, якщо не вдалося.

Використання

add_role($role, $display_name, $capabilities);

$role (рядок) (обов’язковий): Назва ролі: administrator, editor, author, contributor, subscriber.
$display_name (рядок) (обов’язковий): Ім’я для ролі, що відображається: Адміністратор, Автор, Передплатник і т.д.
$capabilities (масив): Масив із можливостями нової ролі. Можливості за замовчуванням
дивіться тут .

За замовчуванням: array()

Приклади

#1 Створимо нову роль

Роль називатиметься basic_contributor, а відображатиметься як “Основний учасник”.

Код має бути запущений лише один раз! Не залишайте його працювати постійно!

$result = add_role( 'basic_contributor', 'Основний учасник',
	array(
		'read' => true, // true дозволяє цю можливість
		'edit_posts' => true, // true дозволяє редагувати пости
		'upload_files' => true, // може завантажувати файли
	)
);
if ( null !== $result ) {
	echo 'Ура! Нова роль створена!';
}
else {
	echo 'Ой... Така роль вже існує.';
}

#2 Створення нової ролі під час активації плагіна

register_activation_hook( __FILE__, 'add_roles_on_plugin_activation' );
function add_roles_on_plugin_activation() {

	add_role( 'custom_role', 'Custom Subscriber',
		array(
			'read' => true,
			'level_0' => true
		)
	);
}

#3 Створення нової ролі при активації теми та видалення ролі при деактивації теми

// Видаляємо роль при деактивації нашої теми
add_action( 'switch_theme', 'deactivate_my_theme');
function deactivate_my_theme() {
	remove_role( 'basic_contributor');
}

// Додаємо роль при активації нашої теми
add_action( 'after_switch_theme', 'activate_my_theme');
function activate_my_theme() {
	add_role( 'basic_contributor', 'Основний учасник',
		[
			'read' => true, // true дозволяє цю можливість
			'edit_posts' => true, // true дозволяє редагувати пости
			'upload_files' => true, // може завантажувати файли
		]
	);
}

Подробиці читайте в описі до хуків after_switch_theme .

#4 Наслідуємо можливості ролі “Автор”

register_activation_hook( __FILE__, 'add_roles_on_plugin_activation' );

function add_roles_on_plugin_activation() {

	// Отримаємо об'єкт даних ролі "Автор"
	$ author = get_role( 'author');

	// Створимо нову роль і наділимо її правами "Автора"
	add_role( 'project_manager', 'Керівник проекту', $author->capabilities );
}

список змін

З версії 2.0.0

Введено.

add role ^{WP 6.0.2}

wp-includes/capabilities.php

function add_role( $role, $display_name, $capabilities = array() ) {
	if (empty($role)) {
		return;
	}
	return wp_roles()->add_role( $role, $display_name, $capabilities );
}