Функция add_role() в WordPress: создание и управление пользовательскими ролями

Функция add_role() позволяет добавлять новые пользовательские роли в WordPress с набором возможностей (capabilities). Она особенно полезна при разработке тем и плагинов, когда нужно создать новую роль для управления доступом к различным частям системы.

add_role( string $role, string $display_name, bool[] $capabilities = array() ): WP_Role|void

Параметры:

• $role (строка, обязательный): Имя новой роли, которое будет использоваться для внутренних операций (например, basic_contributor).
• $display_name (строка, обязательный): Человекочитаемое имя роли, которое будет отображаться в админ-панели (например, Основной участник).
• $capabilities (массив, необязательный): Массив возможностей роли, где ключами являются имена возможностей, а значениями — логические значения (true для разрешения и false для запрета).

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

• WP_Role: Объект роли, если роль успешно добавлена.
• null: Если роль уже существует.

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

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

Пример 1: Создание роли «Контент-менеджер»

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

$result = add_role(
    'content_manager',
    'Контент-менеджер',
    array(
        'read'           => true,   // Разрешаем чтение
        'edit_posts'     => true,   // Разрешаем редактирование постов
        'delete_posts'   => false,  // Запрещаем удаление постов
        'publish_posts'  => true,   // Разрешаем публикацию постов
    )
);

if ($result !== null) {
    echo 'Роль "Контент-менеджер" успешно добавлена.';
} else {
    echo 'Роль уже существует.';
}

Примечание: Мы отключаем возможность удаления постов, чтобы избежать случайных ошибок со стороны контент-менеджеров.

Пример 2: Добавление роли при активации плагина

Рекомендуется вызывать функцию add_role() в хуке активации плагина, чтобы роль была добавлена только при первой установке. Рассмотрим сценарий создания роли «Ограниченный участник», которому разрешено только редактировать и просматривать свои посты.

register_activation_hook(__FILE__, 'add_limited_role');

function add_limited_role() {
    add_role(
        'limited_contributor',
        'Ограниченный участник',
        array(
            'read'           => true,
            'edit_posts'     => true,
            'delete_posts'   => false,  // Ограничиваем возможность удаления
            'upload_files'   => false,  // Запрещаем загрузку файлов
        )
    );
}

Здесь роль имеет только базовые права: редактировать свои записи и читать контент, но не может загружать файлы или удалять посты.

Пример 3: Создание роли для модерирования комментариев

Если нужно создать роль, специализирующуюся на управлении комментариями, например, «Модератор комментариев», который не может редактировать посты, но имеет полный доступ к комментариям:

add_role(
    'comment_moderator',
    'Модератор комментариев',
    array(
        'moderate_comments' => true,  // Разрешаем модерировать комментарии
        'read'              => true,  // Доступ к панели
        'edit_posts'        => false, // Ограничиваем редактирование постов
    )
);

Такой пользователь сможет модерировать комментарии на сайте, но не сможет изменять записи или загружать медиафайлы.

Пример 4: Удаление роли и повторное создание

Если необходимо обновить права существующей роли, сначала её нужно удалить с помощью remove_role(), затем снова добавить с новыми правами. Например, обновим возможности роли «Руководитель проекта»:

function update_project_manager_role() {
    remove_role('project_manager');  // Удаляем старую роль

    add_role(
        'project_manager',
        'Руководитель проекта',
        array(
            'read'              => true,
            'edit_posts'        => true,
            'edit_pages'        => true,
            'manage_options'    => true,  // Новая возможность: управление настройками сайта
            'delete_pages'      => false,
        )
    );
}
add_action('init', 'update_project_manager_role');

Здесь мы добавляем возможность управления настройками сайта для «Руководителя проекта», а удаление страниц остается недоступным.

Пример 5: Наследование прав от другой роли

Можно создать новую роль, которая будет иметь тот же набор прав, что и другая роль. Например, создадим роль «Менеджер проектов» на основе возможностей администратора:

function add_project_manager_role() {
    $admin_role = get_role('administrator');  // Получаем возможности администратора

    add_role(
        'project_manager',
        'Менеджер проектов',
        $admin_role->capabilities  // Наследуем все права администратора
    );
}
add_action('init', 'add_project_manager_role');

Этот пример показывает, как можно создать роль с правами, идентичными роли администратора, без необходимости перечислять все возможности вручную.

Пример 6: Добавление роли при активации темы

Функция add_role() также может быть использована при активации темы. В этом примере создадим роль «Поддержка клиентов», которая будет добавлена при активации темы и удалена при ее деактивации.

// Добавляем роль при активации темы
add_action('after_switch_theme', 'activate_theme_role');
function activate_theme_role() {
    add_role(
        'customer_support',
        'Поддержка клиентов',
        array(
            'read'              => true,
            'edit_posts'        => false,
            'moderate_comments' => true,  // Разрешаем управление комментариями
        )
    );
}

// Удаляем роль при деактивации темы
add_action('switch_theme', 'deactivate_theme_role');
function deactivate_theme_role() {
    remove_role('customer_support');  // Удаляем роль
}

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

Когда использовать и что учитывать

1. Вызывать один раз: Не вызывайте add_role() при каждом загрузке страницы, чтобы избежать излишней нагрузки на базу данных.
2. Удаление ролей: Если нужно изменить права существующей роли, лучше сначала удалить её с помощью remove_role(), а затем снова добавить с обновленными правами.
3. Безопасность: Убедитесь, что вы назначаете правильные права пользователям, особенно если они могут влиять на настройки сайта.

Заключение

Функция add_role() — мощный инструмент для гибкого управления пользователями в WordPress. Она позволяет создавать новые роли с определенными правами доступа, адаптируя функциональность сайта под конкретные нужды проекта. Используя add_role() в сочетании с активацией плагинов или тем, можно эффективно управлять правами пользователей, избегая лишней нагрузки на сервер.