# Announcing Acorn User Roles

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](https://github.com/roots/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

```

 Copy

Once installed, you can publish the configuration file:

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

```

 Copy

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,
    ],
],

```