Announcing Acorn User Roles

Ben Word 2026-03-06

WordPress’s native approach to managing user roles involves scattered add_role() and remove_role() calls that are easy to lose track of and difficult to keep consistent across environments. Role changes persist in the database, making it hard to know what the current state should be just by reading your code.

Introducing Acorn User Roles — a new package that allows you to manage user roles through a straightforward PHP config file.

Usage

$ composer require roots/acorn-user-roles

Once installed, you can publish the configuration file:

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

User roles are configured using a simple array structure in config/user-roles.php:

<?php

return [

    /*
    |--------------------------------------------------------------------------
    | User Roles
    |--------------------------------------------------------------------------
    |
    | Define user roles to add or remove. Each key is the role slug.
    |
    | Set a role to `false` to remove it. Otherwise, provide an array with
    | `display_name` and `capabilities` to add or update the role.
    |
    | Capabilities can be a simple list (['read', 'edit_posts']) or an
    | associative array (['read' => true, 'edit_posts' => false]).
    |
    | Capabilities defined here are synced on every request. Capabilities
    | not listed are left untouched (e.g. those added by other plugins).
    |
    | Set `strict` to `true` on a role to make config authoritative —
    | any unlisted capabilities will be removed.
    |
    */

    'subscriber' => false,

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

Acorn User Roles will automatically register, update, or remove your user roles on every request — keeping your environments convergent.

Capabilities defined in config are synced on every request, but capabilities added by other plugins are left untouched. To explicitly deny a capability, set it to false:

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

If you want the config to be the single source of truth for a role, set strict to true — any capabilities not listed will be removed:

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