Logical split of roles and user usage instructions

docs/README.md

@@ -1,18 +1,19 @@
 # TinyAuth Authorization
 The fast and easy way for user authorization in CakePHP 3.x applications.
 
-Enable TinyAuth Authorize adapter if you want to add instant (and easy) role based
-access (RBAC) to your application.
+Enable TinyAuth Authorize adapter if you want to add instant (and easy) role
+based access (RBAC) to your application.
 
 ## Basic Features
-- Singe or multi role
+- Single or multi role
 - DB (dynamic) or Configure based role definition
 - INI file (static) based access rights (controller-action/role setup)
 - Lightweight and incredibly fast
 
 Do NOT use if
 - you need ROW based access
-- you want to dynamically adjust access rights (or enhance it with a web frontend yourself)
+- you want to dynamically adjust access rights (or enhance it with a web
+frontend yourself)
 
 ## Enabling
 
@@ -30,19 +31,30 @@ public function beforeFilter(Event $event) {
 	$this->loadComponent('Auth', [
 		'authorize' => [
 			'TinyAuth.Tiny' => [
+				'multiRole' => false,
 				'allowUser' => false,
 				'authorizeByPrefix' => false,
 				'prefixes' => [],
-				'superAdminRole' => null
+				'superAdminRole' => null,
+				'autoClearCache' => false
 			]
 		]
 	]);
 }
 ```
 
+> Please note that TinyAuth Authorize can be used in combination with any
+> [CakePHP Authentication Type](http://book.cakephp.org/3.0/en/controllers/components/authentication.html#choosing-an-authentication-type).
+
 ## Roles
 
-You need to define some roles for TinyAuth to work, for example:
+TinyAuth requires the presence of roles to function so create those first using
+one of the following two options.
+
+### Configure based roles
+
+Define your roles in a Configure array if you want to prevent database role
+lookups, for example:
 
 ```php
 // config/app_custom.php
@@ -63,10 +75,52 @@ return [
 ];
 ```
 
-You do not have to configure the Roles array if you use DB driven roles.
-You can however avoid the DB lookups this way if you want to.
-For the DB driven approach make sure you have an "alias" field in your roles table
-as slug identifier for the acl.ini file.
+### Database roles
+When you choose to store your roles in the database TinyAuth expects a table
+named ``roles``. If you prefer to use another table name simply specify it using the
+``rolesTable`` configuration option.
+
+>**Note:** make sure to add an "alias" field to your roles table (used as slug
+identifier in the acl.ini file)
+
+Example of a record from a valid roles table:
+
+```php
+'id' => '11'
+'name' => 'User'
+'description' => 'Basic authenticated user'
+'alias' => 'user'
+'created' => '2010-01-07 03:36:33'
+'modified' => '2010-01-07 03:36:33'
+```
+
+> Please note that you do NOT need Configure based roles when using database
+> roles. Also make sure to remove (or rename) existing Configure based roles
+> since TinyAuth will always first try to find a matching Configure roles array
+> before falling back to using the database.
+
+## Users
+
+### Single-role
+
+When using the single-role-per-user model TinyAuth expects your Users model to
+contain an column named ``role_id``. If you prefer to use another column name
+simply specify it using the ``roleColumn`` configuration option.
+
+### Multi-role
+When using the multiple-roles-per-user model:
+
+- your database MUST have a ``roles`` table
+- your database MUST have a valid join table (e.g. ``roles_users``)
+- the configuration option ``multiRole`` MUST be set to ``true``
+
+Example of a record from a valid join table:
+
+```php
+'id' => 1
+'user_id' => 1
+'role_id' => 1
+```
 
 ## acl.ini
 
@@ -125,6 +179,24 @@ view, edit = user
 * = admin
 ```
 
+## Caching
+
+TinyAuth makes heavy use of caching to achieve optimal performance.
+
+You may however want to disable caching while developing RBAC to prevent
+confusing (outdated) results.
+
+To disable caching either:
+
+- pass ``true`` to the ``autoClearCache`` configuration option
+- use the example below to disable caching automatically for CakePHP debug mode
+
+```php
+'TinyAuth.Tiny' => [
+	'autoClearCache' => Configure::read('debug')
+]
+```
+
 ## Configuration
 
 TinyAuth supports the following configuration options.