Merge remote-tracking branch 'origin/9.next' into 11.next-cake4

Author: skie

.semver

@@ -1,5 +1,5 @@
 ---
-:major: 9
-:minor: 2
+:major: 11
+:minor: 0
 :patch: 0
 :special: ''

Docs/Documentation/Authentication.md

@@ -2,15 +2,15 @@ Authentication
 ==============
 This plugin uses the new authentication plugin [cakephp/authentication](https://github.com/cakephp/authentication/)
 instead of CakePHP Authentication component, but don't worry, the default configuration should be enough for your
-projects. 
+projects.
 
 We've tried to simplify configuration as much as possible using defaults, but keep the ability to override them when needed.
 
 Authentication Component
 ------------------------
 
-The default behavior is to load the authentication component at UsersController, 
-defining the default urls for loginAction, loginRedirect, logoutRedirect but not requiring 
+The default behavior is to load the authentication component at UsersController,
+defining the default urls for loginAction, loginRedirect, logoutRedirect but not requiring
 the request to have a identity.
 
 If you prefer to load the component yourself you can set 'Auth.AuthenticationComponent.load':
@@ -29,7 +29,7 @@ $user = $this->Authentication->getIdentity()->getOriginalData();
 ```
 The default configuration for Auth.AuthenticationComponent is:
 
-```
+```php
 [
     'load' => true,
     'loginRedirect' => '/',
@@ -57,25 +57,23 @@ list of authenticators includes:
 
 These authenticators should be enough for your application, but you easily customize it
 setting the Auth.Authenticators config key.
-  
-For example if you add JWT authenticator you can set:
 
-```
-$authenticators = Configure::read('Auth.Authenticators');
-$authenticators['Jwt'] = [
-    'className' => 'Authentication.Jwt',
+For example if you add JWT authenticator you must add this to your config/users.php file:
+
+```php
+'Auth.Authenticators.Jwt' => [
     'queryParam' => 'token',
     'skipTwoFactorVerify' => true,
-]; 
-Configure::write('Auth.Authenticators', $authenticators);
+    'className' => 'Authentication.Jwt',
+],
+```
 
-``` 
 **You may have noticed the 'skipTwoFactorVerify' option, this option is used to identify if a authenticator should skip
 the two factor flow**
 
 The authenticators are loaded by \CakeDC\Users\Loader\AuthenticationServiceLoader class at load authentication
 service method from plugin object.
- 
+
 See the full Auth.Authenticators at config/users.php
 
 Identifiers
@@ -86,11 +84,12 @@ The identifies are defined to work correctly with the default authenticators, we
 - CakeDC/Users.Social, for Social and SocialPendingEmail authenticators
 - Authentication.Token, for TokenAuthenticator
 
-As you add more authenticators you may need to add identifiers, please check identifiers available at 
+As you add more authenticators you may need to add identifiers, please check identifiers available at
 [official documentation](https://github.com/cakephp/authentication/blob/master/docs/Identifiers.md)
 
 The default value for Auth.Identifiers is:
-```
+
+```php
 [
     'Password' => [
         'className' => 'Authentication.Password',
@@ -127,14 +126,15 @@ For both form login and social login we use a base component 'CakeDC/Users.Login
 it check the result of authentication service to redirect user to a internal page or show an authentication
 error. It provide some error messages for specific authentication result status, please check the config/users.php file.
 
-To use a custom component to handle the login you could do:
+To use a custom component to handle the login you should update your config/users.php file with:
+
+```php
+'Auth.SocialLoginFailure.component' => 'MyLoginA',
+'Auth.FormLoginFailure.component' => 'MyLoginB',
 ```
-Configure::write('Auth.SocialLoginFailure.component', 'MyLoginA');
-Configure::write('Auth.FormLoginFailure.component', 'MyLoginB');
-``` 
 
 The default configuration are:
-```
+```php
 [
     ...
     'Auth' => [
@@ -165,24 +165,24 @@ The default configuration are:
         ...
     ]
 ]
-``` 
+```
 
-Authentication Service Loader 
+Authentication Service Loader
 -----------------------------
 To make the integration with cakephp/authentication easier we load the authenticators and identifiers
 defined at Auth configuration and other components to work with social provider, two-factor authentication.
 
-If the configuration is not enough for your project you may create a custom loader extending the 
+If the configuration is not enough for your project you may create a custom loader extending the
 default provided.
 
 - Create file src/Loader/AppAuthenticationServiceLoader.php
 
-```
+```php
 <?php
 namespace App\Loader;
- 
+
 use \CakeDC\Users\Loader\AuthenticationServiceLoader;
- 
+
 class AppAuthenticationServiceLoader extends AuthenticationServiceLoader
 {
     /**
@@ -202,8 +202,8 @@ class AppAuthenticationServiceLoader extends AuthenticationServiceLoader
     }
 }
 ```
-- Change the authentication service loader:
+- Add this to your config/users.php file to change the authentication service loader:
 
-```
-Configure::write('Authentication.serviceLoader', \App\Loader\AuthenticationServiceLoader::class);
+```php
+'Auth.Authentication.serviceLoader' => \App\Loader\AuthenticationServiceLoader::class,
 ```

Docs/Documentation/Authorization.md

@@ -6,22 +6,25 @@ projects. We tried to allow you to start quickly without the need to configure a
 allow you to configure as much as possible.
 
 
-If you don't want the plugin to autoload setup authorization, you can do:
-```
-Configure::write('Auth.Authorization.enabled', false);
+If you don't want the plugin to autoload setup authorization, you can disable
+in your config/users.php with:
+
+```php
+'Auth.Authorization.enabled' => false,
 ```
 
 Authorization Middleware
 ------------------------
 We load the RequestAuthorization and Authorization middleware with OrmResolver and RbacProvider(work with RequestAuthorizationMiddleware).
 
-The middleware accepts some additional configurations, you can do:
-```
-Configure::write('Auth.AuthorizationMiddleware', $config);
+The middleware accepts some additional configurations, you can update in your
+config/users.php file:
+```php
+'Auth.AuthorizationMiddleware' => $config,
 ```
 
 The default configuration for authorization middleware is:
-```
+```php
 [
     'unauthorizedHandler' => [
         'className' => 'CakeDC/Users.DefaultRedirect',
@@ -41,7 +44,7 @@ The `CakeDC/Users.DefaultRedirect` offers additional behavior and config:
 
 You could do the following to set a custom url and flash message:
 
-```
+```php
 [
     'unauthorizedHandler' => [
         'className' => 'CakeDC/Users.DefaultRedirect',
@@ -61,7 +64,7 @@ You could do the following to set a custom url and flash message:
 ],
 ```
 OR
-```
+```php
 [
     'unauthorizedHandler' => [
         'className' => 'CakeDC/Users.DefaultRedirect',
@@ -82,9 +85,10 @@ OR
 Authorization Component
 -----------------------
 We autoload the authorization component at users controller using the default configuration,
-if you don't want the plugin to autoload it, you can do:
-```
-Configure::write('Auth.AuthorizationComponent.enabled', false);
+if you don't want the plugin to autoload it, you can add this to your config/users.php file:
+
+```php
+'Auth.AuthorizationComponent.enabled' => false,
 ```
 
 You can check the configuration options available for authorization component at the
@@ -100,7 +104,7 @@ default provided.
 
 - Create file src/Loader/AppAuthorizationServiceLoader.php
 
-```
+```php
 <?php
 namespace App\Loader;
 
@@ -127,8 +131,8 @@ class AppAuthorizationServiceLoader
     }
 }
 ```
-- Change the authorization service loader:
+- Add this to your config/users.php file to change the authorization service loader:
 
-```
-Configure::write('Auth.Authorization.serviceLoader', \App\Loader\AppAuthorizationServiceLoader::class);
+```php
+'Auth.Authorization.serviceLoader' => \App\Loader\AppAuthorizationServiceLoader::class,
 ```

Docs/Documentation/Configuration.md

@@ -6,12 +6,11 @@ Overriding the default configuration
 
 For easier configuration, you can specify an array of config files to override the default plugin keys this way:
 
-config/bootstrap.php
+Make sure you loaded the plugin and is using a custom config/users.php file at Application::bootstrap
 ```
 // The following configuration setting must be set before loading the Users plugin
+$this->addPlugin(\CakeDC\Users\Plugin::class);
 Configure::write('Users.config', ['users']);
-Plugin::load('CakeDC/Users', ['routes' => true, 'bootstrap' => true]);
-Configure::write('Users.Social.login', true); //to enable social login
 ```
 
 Configuration for social login
@@ -28,13 +27,14 @@ $ composer require league/oauth1-client:@stable
 
 NOTE: twitter uses league/oauth1-client package
 
-config/bootstrap.php
-```
-Configure::write('OAuth.providers.facebook.options.clientId', 'YOUR APP ID');
-Configure::write('OAuth.providers.facebook.options.clientSecret', 'YOUR APP SECRET');
+And update your config/users.php file:
 
-Configure::write('OAuth.providers.twitter.options.clientId', 'YOUR APP ID');
-Configure::write('OAuth.providers.twitter.options.clientSecret', 'YOUR APP SECRET');
+```php
+'Users.Social.login' => true,
+'OAuth.providers.facebook.options.clientId' => 'YOUR APP ID',
+'OAuth.providers.facebook.options.clientSecret' => 'YOUR APP SECRET',
+'OAuth.providers.twitter.options.clientId' => 'YOUR APP ID',
+'OAuth.providers.twitter.options.clientSecret' => 'YOUR APP SECRET',
 ```
 
 Or use the config override option when loading the plugin (see above)
@@ -44,15 +44,18 @@ Additionally you will see you can configure two more keys for each provider:
 * linkSocialUri (default: /link-social/**provider**),
 * callbackLinkSocialUri(default: /callback-link-social/**provider**)
 
-Those keys are needed to link an existing user account to a third-party account. **Remember to add the callback to your thrid-party app** 
+Those keys are needed to link an existing user account to a third-party account. **Remember to add the callback to your thrid-party app**
 
 Configuration for reCaptcha
 ---------------------
-```
-Configure::write('Users.reCaptcha.key', 'YOUR RECAPTCHA KEY');
-Configure::write('Users.reCaptcha.secret', 'YOUR RECAPTCHA SECRET');
-Configure::write('Users.reCaptcha.registration', true); //enable on registration
-Configure::write('Users.reCaptcha.login', true); //enable on login
+To enable reCaptcha you need to register your site at google reCaptcha console
+and add this to your config/users.php file:
+
+```php
+'Users.reCaptcha.key' => 'YOUR RECAPTCHA KEY',
+'Users.reCaptcha.secret' => 'YOUR RECAPTCHA SECRET',
+'Users.reCaptcha.registration' => true, //enable on registration
+'Users.reCaptcha.login' => true, //enable on login
 ```
 
 
@@ -70,10 +73,11 @@ and [cakephp/authorization](https://github.com/cakephp/authorization) plugins we
 into their documentation for more information.
 
 Most authentication/authorization configuration is defined at 'Auth' key, for example
-if you don't want the plugin to autoload the authorization service, you could do:
+if you don't want the plugin to autoload the authorization service, you could add this
+to your config/users.php file:
 
 ```
-Configure::write('Auth.Authorization.enable', false)
+'Auth.Authorization.enable' => false,
 ```
 
 Interesting Users options and defaults
@@ -163,25 +167,17 @@ To learn more about it please check the configurations for [Authentication](Auth
 
 You need to configure 2 things (version 9.0.4):
 
-* Change the Password identifier fields and the Authenticator for Forms configuration to let it use the email instead of the username for user identify. Add this to your Application class, right before CakeDC/Users Plugin is loaded.
+* Change the Password identifier fields and the Authenticator for Forms
+configuration to let it use the email instead of the username for
+user identify. Add this to your config/users.php:
 
 ```php
-        // Load more plugins here
-        $identifiers = Configure::read('Auth.Identifiers');
-        $identifiers['Password']['fields']['username'] = 'email';
-        Configure::write('Auth.Identifiers', $identifiers);
-
-        $authenticators = Configure::read('Auth.Authenticators');
-        $authenticators['Form']['fields']['username'] = 'email';
-        Configure::write('Auth.Authenticators', $authenticators);
-
-        //Configure::write('Users.config', ['users', 'permissions']);
-        
-        $this->addPlugin(\CakeDC\Users\Plugin::class);
+'Auth.Identifiers.Password.fields.username' => 'email',
+'Auth.Authenticators.Form.fields.username' => 'email',
 ```
 
-* Override the login.php template to change the Form->control to "email". 
-Add (or copy from the [/templates/Users/login.php](../../templates/Users/login.php)) the file login.php to path /templates/plugin/CakeDC/Users/Users/login.php 
+* Override the login.php template to change the Form->control to "email".
+Add (or copy from the [/templates/Users/login.php](../../templates/Users/login.php)) the file login.php to path /templates/plugin/CakeDC/Users/Users/login.php
 and ensure it has the following content
 
 ```php