add_role()
Добавляет новую роль в WordPress.
Функция должна быть вызвана всего один раз. Потому что она изменяет данные в базе данных (таблица wp_options, поле wp_user_roles). Поэтому лучше изменять их во время активации/деактивации плагина или темы, см. пример.
Когда вызывать
Перед тем как добавлять или изменять роль, убедитесь что глобальная переменная $wp_roles доступна. Лучше всего использовать хуки активации плагинов или тем, чтобы добавить новую роль. За хук активации плагина отвечает функция: register_activation_hook().
Удаление существующей роли
Если вы создаете новую роль и указываете ей возможности, то убедитесь, что такой роли не существует. Эта функция не будет работать если роль уже существует в базе данных.
Вариант решения такой проблемы, перед созданием роли её можно удалить, используя функцию remove_role(), в которой указать создаваемую вами роль.
Хуков нет.
Возвращает
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, // может загружать файлы
]
);
}
Подробности читайте в описании к хукам switch_theme и 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() add role WP 6.5.2
function add_role( $role, $display_name, $capabilities = array() ) {
if ( empty( $role ) ) {
return;
}
return wp_roles()->add_role( $role, $display_name, $capabilities );
}