Добавление новой роли в WordPress с помощью функции add_role()

# Функция add_role() │ WP 2.0.0

Функция add_role() позволяет добавить новую роль в WordPress.

Эта функция должна вызываться только один раз, так как она изменяет данные в базе данных (в таблице wp_options в поле wp_user_roles). Поэтому лучше добавлять или изменять роли во время активации или деактивации плагина или темы (см. пример ниже).

## Когда использовать

Перед добавлением или изменением ролей убедитесь, что глобальная переменная $wp_roles доступна. Лучше всего использовать хуки активации или деактивации плагина/темы для добавления новых ролей. Чтобы добавить хук активации плагина, используйте функцию register_activation_hook().

## Удаление существующей роли

Если вы создаете новую роль и назначаете ей права, убедитесь, что такой роли еще не существует, потому что эта функция не сработает, если роль уже есть.

Чтобы избежать этой проблемы, вы можете использовать функцию remove_role() перед созданием новой роли.

## Пример использования

### Возвращаемое значение

Возвращает объект WP_Role или null. Возвращается объект WP_Role, если роль добавлена.

### Синтаксис

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

• $role (string) (обязательный) — имя роли: например, administrator, editor, author, contributor, subscriber.
• $display_name (string) (обязательный) — отображаемое имя для роли: например, Administrator, Author, Subscriber и т.д.
• $capabilities (array) — список прав, например, array( 'edit_posts' => true, 'delete_posts' => false ). По умолчанию: array().

Примеры

1. Создание новой роли при активации плагина и удаление её при деактивации

// Удаление роли при деактивации плагина
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', 'Basic Contributor',
        [
            'read'         => true,
            'edit_posts'   => true,
            'upload_files' => true,
        ]
    );
}

2. Создание новой роли

Имя новой роли будет basic_contributor, а отображаемое имя — "Basic Contributor".

Важно: этот код должен выполняться только один раз! Не оставляйте его на постоянной основе!

$result = add_role( 'basic_contributor', 'Basic Contributor',
    array(
        'read'         => true, 
        'edit_posts'   => true, 
        'upload_files' => true, 
    )
);
if ( null !== $result ) {
    echo 'Ура! Новая роль создана!';
} else {
    echo 'Упс... Эта роль уже существует.';
}

3. Создание новой роли при активации плагина

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 ) );
}

4. Унаследование прав от роли "Автор"

$author = get_role( 'author' );
add_role( 'project_manager', 'Project Manager', $author->capabilities );

Изменения

С версии 2.0.0 функция была добавлена.

Код функции add_role()

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

    return wp_roles()->add_role( $role, $display_name, $capabilities );
}

Связанные функции

• author_can()
• current_user_can()
• get_editable_roles()
• get_role()
• grant_super_admin()
• is_super_admin()
• map_meta_cap()
• remove_role()
• user_can()
• wp_roles()
• WP_Roles::add_cap()
• WP_User::add_cap()