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]).
    |
    | Config is authoritative — existing roles will be synced to match,
    | and 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 and your config the single source of truth.