From 0af55ad77c2a8ff3b2ffaec423091f60d71b4574 Mon Sep 17 00:00:00 2001
From: Marco <marco1@live.de>
Date: Sat, 29 Jul 2017 23:21:57 +0200
Subject: [PATCH] Document features related to roles in 'Administration'
 interface

---
 README.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)

diff --git a/README.md b/README.md
index 2b9b0bd..c907be2 100644
--- a/README.md
+++ b/README.md
@@ -71,6 +71,9 @@ Migrating from an earlier version of this project? See our [upgrade guide](Migra
  * [Administration (managing users)](#administration-managing-users)
    * [Creating new users](#creating-new-users)
    * [Deleting users](#deleting-users)
+   * [Assigning roles to users](#assigning-roles-to-users)
+   * [Taking roles away from users](#taking-roles-away-from-users)
+   * [Checking roles](#checking-roles)
  * [Utilities](#utilities)
    * [Creating a random string](#creating-a-random-string)
    * [Creating a UUID v4 as per RFC 4122](#creating-a-uuid-v4-as-per-rfc-4122)
@@ -610,6 +613,86 @@ catch (\Delight\Auth\AmbiguousUsernameException $e) {
 }
 ```
 
+#### Assigning roles to users
+
+```php
+try {
+    $auth->admin()->addRoleForUserById($userId, \Delight\Auth\Role::ADMIN);
+}
+catch (\Delight\Auth\UnknownIdException $e) {
+    // unknown user ID
+}
+
+// or
+
+try {
+    $auth->admin()->addRoleForUserByEmail($userEmail, \Delight\Auth\Role::ADMIN);
+}
+catch (\Delight\Auth\InvalidEmailException $e) {
+    // unknown email address
+}
+
+// or
+
+try {
+    $auth->admin()->addRoleForUserByUsername($username, \Delight\Auth\Role::ADMIN);
+}
+catch (\Delight\Auth\UnknownUsernameException $e) {
+    // unknown username
+}
+catch (\Delight\Auth\AmbiguousUsernameException $e) {
+    // ambiguous username
+}
+```
+
+#### Taking roles away from users
+
+```php
+try {
+    $auth->admin()->removeRoleForUserById($userId, \Delight\Auth\Role::ADMIN);
+}
+catch (\Delight\Auth\UnknownIdException $e) {
+    // unknown user ID
+}
+
+// or
+
+try {
+    $auth->admin()->removeRoleForUserByEmail($userEmail, \Delight\Auth\Role::ADMIN);
+}
+catch (\Delight\Auth\InvalidEmailException $e) {
+    // unknown email address
+}
+
+// or
+
+try {
+    $auth->admin()->removeRoleForUserByUsername($username, \Delight\Auth\Role::ADMIN);
+}
+catch (\Delight\Auth\UnknownUsernameException $e) {
+    // unknown username
+}
+catch (\Delight\Auth\AmbiguousUsernameException $e) {
+    // ambiguous username
+}
+```
+
+#### Checking roles
+
+```php
+try {
+    if ($auth->admin()->doesUserHaveRole($userId, \Delight\Auth\Role::ADMIN)) {
+        // the specified user is an administrator
+    }
+    else {
+        // the specified user is *not* an administrator
+    }
+}
+catch (\Delight\Auth\UnknownIdException $e) {
+    // unknown user ID
+}
+```
+
 ### Utilities
 
 #### Creating a random string