roots/acorn-user-roles

Simple user role management for Acorn.

v1.1.0 2026-03-11 14:57 UTC

Requires

• php: >=8.2

Requires (Dev)

• laravel/pint: ^1.27
• roots/acorn: ^5.0

MIT

• Roots Team

README

Simple user role management for Acorn.

Support us

We're dedicated to pushing modern WordPress development forward through our open source projects, and we need your support to keep building. You can support our work by purchasing Radicle, our recommended WordPress stack, or by sponsoring us on GitHub. Every contribution directly helps us create better tools for the WordPress ecosystem.

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