README

Simple user role management for Acorn.

Support us

Roots is an independent open source org, supported only by developers like you. Your sponsorship funds WP Packages and the entire Roots ecosystem, and keeps them independent. Support us by purchasing Radicle or sponsoring us on GitHub — sponsors get access to our private Discord.

Requirements

• PHP >= 8.2
• Acorn >= 5.0

Installation

Install via Composer:

composer require roots/acorn-user-roles

Getting Started

Start by optionally publishing the user-roles config:

$ wp acorn vendor:publish --provider="Roots\AcornUserRoles\AcornUserRolesServiceProvider"

Usage

User roles can be configured in the published config/user-roles.php file.

Adding a role

'librarian' => [
    'display_name' => 'Librarian',
    'capabilities' => ['read', 'edit_books', 'publish_books'],
],

Capabilities can also be defined as an associative array:

'editor_lite' => [
    'display_name' => 'Editor Lite',
    'capabilities' => [
        'read' => true,
        'edit_posts' => true,
        'delete_posts' => false,
    ],
],

Removing a role

Since roles are stored in the database, removing a role from the config will not delete it. To remove a role, set it to false:

'librarian' => false,
'subscriber' => false,

Note: Setting a role to false permanently removes it from the database. Removing the line from config afterward will not restore it. To restore a removed role, use WP-CLI: wp role reset subscriber (or wp role reset --all to restore all default roles).

Updating an existing role

Capabilities defined in config are synced on every request. If you change the capabilities or display name for an existing role, the configured values will be applied.

Capabilities not included in the config are left untouched, so capabilities added by other plugins are preserved. To explicitly deny a capability, set it to false:

'editor' => [
    'capabilities' => [
        'read' => true,
        'edit_posts' => true,
        'delete_posts' => false, // explicitly denied
    ],
],

Strict mode

If you want the config to be the single source of truth for a role, set strict to true. Any capabilities not listed in the config will be removed. In other words: false denies a listed capability, while strict removes unlisted capabilities.

'editor' => [
    'strict' => true,
    'capabilities' => [
        'read' => true,
        'edit_posts' => true,
    ],
],

Community

Keep track of development and community news.

• Join us on Discord by sponsoring us on GitHub
• Join us on Roots Discourse
• Follow @rootswp on Twitter
• Follow the Roots Blog
• Subscribe to the Roots Newsletter