New major

README.md

@@ -12,25 +12,47 @@ A CakePHP plugin to handle authentication and user authorization the easy way.
 
 This branch is for **CakePHP 5.1+**. For details see [version map](https://github.com/dereuromark/cakephp-tinyauth/wiki#cakephp-version-map).
 
-## Features
-
-### Authentication
-What are public actions, which ones need login?
-
-- Powerful default configs to get you started right away.
-- [Quick Setup](https://github.com/dereuromark/cakephp-tinyauth/blob/master/docs/Authentication.md#quick-setups) for 5 minute integration.
-
-### Authorization
-Once you are logged in, what actions can you see with your role(s)?
-
-- Single-role: 1 user has 1 role (users and roles table for example)
-- Multi-role: 1 user can have 1...n roles (users, roles and a "roles_users" pivot table for example)
-- [Quick Setup](https://github.com/dereuromark/cakephp-tinyauth/blob/master/docs/Authorization.md#quick-setups) for 5 minute integration.
-
-### Useful helpers
-- AuthUser Component and Helper for stateful and stateless "auth data" access.
-- Authentication Component and Helper for `isPublic()` check on current other other actions.
-- Auth DebugKit panel for detailed insights into current URL and auth status, identity content and more.
+## Why use TinyAuth as a wrapper for Authentication/Authorization plugins?
+
+TinyAuth now acts as a powerful wrapper around CakePHP's official Authentication and Authorization plugins, providing significant advantages:
+
+### 🚀 Zero-Code Configuration
+- **INI-based setup**: Define all your authentication and authorization rules in simple INI files
+- **No controller modifications**: Unlike vanilla plugins that require code in every controller
+- **Plugin-friendly**: Automatically works with third-party plugins without modifications
+
+### ⚡ Lightning Fast Setup
+- **5-minute integration**: Get authentication and authorization working in minutes, not hours
+- **Sensible defaults**: Pre-configured settings that work for 90% of use cases
+- **Quick setups**: Built-in configurations for common scenarios (public non-prefixed, admin areas, etc.)
+
+### 🛠️ Developer Experience
+- **Centralized management**: All auth rules in one place, not scattered across controllers
+- **Easy maintenance**: Change access rules without touching code
+- **Cache optimized**: Built-in caching for maximum performance
+- **DebugKit panel**: Visualize auth status, identity, and permissions in real-time
+
+### 🔧 Flexibility
+- **Adapter pattern**: Use INI files, database, or custom adapters for rule storage
+- **Progressive enhancement**: Start simple, add complexity only when needed
+- **Stand-alone components**: Use AuthUser component/helper independently if needed
+
+### 📊 When to Choose TinyAuth
+
+Choose TinyAuth when you want:
+- ✅ Simple role-based access control (RBAC)
+- ✅ Quick setup without extensive configuration
+- ✅ Controller-action level permissions
+- ✅ Easy-to-manage access rules
+- ✅ Minimal code changes
+
+Since this plugin just further extends the official ones, you can skip the plugin's authentication and authorization components, and use the original plugins' functionality if you want:
+- ❌ Complex policy-based authorization
+- ❌ Resource-level permissions (per-entity authorization)
+- ❌ Middleware/routing level authentication
+- ❌ Custom authentication flows
+
+You can still use the other helpers of this plugin, however.
 
 ## What's the idea?
 Default CakePHP authentication and authorization depends on code changes in at least each controller, maybe more classes.

docs/Authentication.md

@@ -42,8 +42,6 @@ At the same time you can always set up "deny" rules for any allowed prefix to re
 
 ## Enabling
 
-**DEPRECATED** Use `TinyAuth.Authentication` instead. Rest of the page is accurate.
-
 Authentication is set up in your controller's `initialize()` method:
 
 ```php
@@ -52,7 +50,7 @@ Authentication is set up in your controller's `initialize()` method:
 public function initialize() {
     parent::initialize();
 
-    $this->loadComponent('TinyAuth.Auth');
+    $this->loadComponent('TinyAuth.Authentication');
 }
 ```
 
@@ -130,14 +128,14 @@ use Cake\Event\EventInterface;
     public function beforeFilter(EventInterface $event): void {
         parent::beforeFilter($event);
 
-        $this->Auth->allow(['index', 'view']);
+        $this->Authentication->allowUnauthenticated(['index', 'view']);
     }
 ```
 This can be interested when migrating slowly to TinyAuth, for example.
 Once you move such a code based rule into the INI file, you can safely remove those lines of code in your controller :)
 
 ### allow() vs deny()
-Since 1.11.0 you can also mix it with `deny()` calls. From how the AuthComponent works, all allow() calls need be done before calling deny().
+Since 1.11.0 you can also mix it with `deny()` calls. From how the Authentication component works, all allow() calls need be done before calling deny().
 As such TinyAuth injects its list now before `Controller::beforeFilter()` gets called.
 
 Note: It is also advised to move away from these controller calls.
@@ -180,7 +178,7 @@ echo $this->Form->control('password', ['autocomplete' => 'off']);
 
 ## Configuration
 
-TinyAuth AuthComponent supports the following configuration options.
+TinyAuth Authentication component supports the following configuration options.
 
 Option | Type | Description
 :----- | :--- | :----------

docs/README.md

@@ -16,7 +16,7 @@ You can activate an "Auth" DebugKit panel to have useful insights per URL.
 See [AuthPanel](AuthPanel.md) docs.
 
 ## Authentication
-This is done via TinyAuth AuthComponent.
+This is done via TinyAuth Authentication component.
 
 The component plays well together with the authorization part (see below).
 If you do not have any roles and either all are logged in or not logged in you can also use this stand-alone to make certain pages public.
@@ -27,7 +27,7 @@ See [Authentication](Authentication.md) docs.
 The TinyAuthorize adapter takes care of authorization.
 
 The adapter plays well together with the component above.
-But if you prefer to control the action whitelisting for authentication via code and `$this->Auth->allow()` calls, you can
+But if you prefer to control the action whitelisting for authentication via code and `$this->Authentication->allowUnauthenticated()` calls, you can
 also just use this adapter stand-alone for the ACL part of your application.
 
 There is also an AuthUserComponent and AuthUserHelper to assist you in making role based decisions or displaying role based links in your templates.
@@ -82,14 +82,29 @@ See the docs for details:
 - [TinyAuth and Authentication plugin](AuthenticationPlugin.md)
 - [TinyAuth and Authorization plugin](AuthorizationPlugin.md)
 
-### When to use the new plugins?
-They are super powerful, but they also require a load of config to get them to run.
-If you need authentication/authorization on middleware/routing level however, you need
-to use them.
+### Why use TinyAuth with the new plugins?
+
+TinyAuth provides a powerful abstraction layer over the official Authentication and Authorization plugins:
 
-If you only need the basic request policy provided by this plugin, and no further ORM or other policies,
-then it is best to stick to the Auth component as simple wrapper.
-It is then limited to controller scope (no middleware/routing support) as it always has been so far.
+**Benefits of using TinyAuth:**
+- **Zero-code configuration**: All auth rules in INI files, no controller modifications needed
+- **Instant setup**: Working authentication/authorization in under 5 minutes
+- **Plugin compatibility**: Works automatically with all plugins without modifications
+- **Centralized management**: All rules in one place, not scattered across controllers
+- **Performance**: Built-in caching for optimal speed
+- **Developer friendly**: DebugKit panel, clear error messages, easy debugging
+
+**When to use vanilla plugins' functionality directly:**
+They are super powerful, but they also require a load of config to get them to run.
+Consider using them (partially) directly when you need:
+- Authentication/authorization on middleware/routing level
+- Complex policy-based authorization (ORM policies, custom voters)
+- Per-entity authorization rules
+- Custom authentication flows
+
+**When to use TinyAuth wrapper:**
+If you only need the basic request policy provided by this plugin (controller-action level permissions),
+then TinyAuth provides a much simpler and faster solution.
 
 You can seamlessly upgrade to the new plugins while keeping your INI files.
 They are also compatible with AuthUser component and helper as well as the Auth panel.

phpstan.neon

@@ -7,5 +7,3 @@ parameters:
 	ignoreErrors:
 		- identifier: missingType.iterableValue
 		- identifier: missingType.generics
-		- '#Constructor of class .+SessionStorage has an unused parameter \$response#'
-		- '#PHPDoc tag @mixin contains invalid type .+InstanceConfigTrait.#'

src/Auth/AclTrait.php

@@ -644,6 +644,7 @@ protected function _mapped(array $roles) {
 				continue;
 			}
 
+			/** @var string $alias */
 			$array[$alias] = $role;
 		}
 

src/Auth/AuthUserTrait.php

@@ -33,7 +33,7 @@
  * define('USER_ROLE_KEY', 'role_id');
  * ```
  *
- * Note: This uses AuthComponent internally to work with both stateful and stateless auth.
+ * Note: This uses Identity from Authentication plugin.
  *
  * @author Mark Scherer
  * @license MIT