Adding/removing user roles

README.md

@@ -110,7 +110,7 @@ Registering a taxonomy is similar to a post type. Looking in `config/poet.php`,
 ],
 ```
 
-The most relevent configuration option is `links` which defines the post type the taxonomy is connected to. If no link is specified, it will default to `post`.
+The most relevant configuration option is `links` which defines the post type the taxonomy is connected to. If no link is specified, it will default to `post`.
 
 To view an archive for the Genre taxonomy, copy the Blade template called `archive.blade.php` to a new file called `taxonomy-genre.blade.php`.
 
@@ -151,6 +151,35 @@ For additional configuration options for taxonomies, please see:
 
 > **Note**: Do not nest configuration in a `config` key like shown in the Extended CPTs documentation.
 
+### Registering a User Role
+
+Registering a user role is similar as a post type or a taxonomy. Looking in `config/poet.php`, you will see a librarian user role:
+
+```php
+'user_role' => [
+    'librarian' => [
+        'display_name' => 'Librarian',
+        'capabilities' => ['read', 'edit_books', 'publish_books', 'edit_others_books'],
+    ],
+],
+```
+
+Also like post types and taxonomies, you can easily unregister an existing user role by simply passing `false`:
+
+```php
+'user_role' => [
+    'editor' => false,
+    'subscriber' => false,
+],
+```
+
+Don't worry, [we are not making a database query on every page load](https://developer.wordpress.org/reference/functions/add_role/#comment-3194). We take advantage of the [wp_roles()->is_role($slug)](https://developer.wordpress.org/reference/classes/wp_roles/is_role/) function to avoid unnecessary database queries.
+
+Please see the WordPress functions for more information:
+
+- [`add_role()`](https://developer.wordpress.org/reference/functions/add_role/)
+- [`remove_role()`](https://developer.wordpress.org/reference/functions/remove_role/)
+
 ### Registering a Block
 
 Poet provides an easy way to register a Gutenberg block with the editor using an accompanying Blade view for rendering the block on the frontend.

config/poet.php

@@ -23,6 +23,7 @@
                 'singular' => 'Book',
                 'plural' => 'Books',
             ],
+            'capability_type'   => 'book',
         ],
     ],
 
@@ -43,6 +44,23 @@
         ],
     ],
 
+    /*
+    |--------------------------------------------------------------------------
+    | User Roles
+    |--------------------------------------------------------------------------
+    |
+    | Here you may specify the user roles to be registered or removed by Poet
+    |
+    */
+
+    'user_role' => [
+        'librarian' => [
+            'display_name' => 'Librarian',
+            'capabilities' => ['read', 'edit_books', 'publish_books', 'edit_others_books'],
+        ],
+        // 'editor' => false,
+    ],
+
     /*
     |--------------------------------------------------------------------------
     | Blocks

src/Modules/UserRoleModule.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace Log1x\Poet\Modules;
+
+use Illuminate\Support\Str;
+use Illuminate\Support\Arr;
+
+class UserRoleModule extends AbstractModule
+{
+    /**
+     * The module key.
+     *
+     * @var string
+     */
+    protected $key = 'user_role';
+
+    /**
+     * Handle the module.
+     *
+     * @return void
+     */
+    public function handle()
+    {
+        $this->config->each(function ($value, $key) {
+            /**
+             * Avoids slow database query
+             * https://developer.wordpress.org/reference/functions/add_role/#comment-3194
+             */
+            if (wp_roles()->is_role($key)) {
+                if ($value === false) {
+                    remove_role($key);
+                }
+                return;
+            }
+
+            if ($value === false) {
+                return;
+            }
+
+            $displayName = $value['display_name'] ?? Str::title($key);
+            $capabilities = $value['capabilities'] ?? ['read'];
+            if (!is_array($capabilities)) {
+                wp_die(esc_html__('Expected capabilities fields to be an array'));
+            }
+
+            if (!Arr::isAssoc($capabilities)) {
+                $capabilities = $this->enableUserCapabilities($capabilities);
+            }
+
+            add_role($key, $displayName, $capabilities);
+        });
+    }
+
+    /**
+     * Converts an array like this ['read', 'edit_posts'] into ['read' => true, 'edit_posts' => true]
+     *
+     * @param   array<string> $capabilities - List of capabilities to be enabled in role.
+     * @return  array<string,true>
+     */
+    protected function enableUserCapabilities($capabilities)
+    {
+        return collect($capabilities)
+            ->mapWithKeys(function (string $capability, int $key) {
+                return [$capability => true];
+            })
+            ->toArray();
+    }
+}

src/Poet.php

@@ -2,7 +2,6 @@
 
 namespace Log1x\Poet;
 
-use Illuminate\Support\Collection;
 use Log1x\Poet\Concerns\HasCollection;
 use Log1x\Poet\Modules\AbstractModule;
 use Log1x\Poet\Modules\AdminMenuModule;
@@ -13,10 +12,9 @@
 use Log1x\Poet\Modules\EditorPaletteModule;
 use Log1x\Poet\Modules\PostTypeModule;
 use Log1x\Poet\Modules\TaxonomyModule;
+use Log1x\Poet\Modules\UserRoleModule;
 use Roots\Acorn\Application;
 
-use function Roots\asset;
-
 class Poet
 {
     use HasCollection;
@@ -49,6 +47,7 @@ class Poet
         EditorPaletteModule::class,
         TaxonomyModule::class,
         PostTypeModule::class,
+        UserRoleModule::class,
     ];
 
     /**