Merge pull request #12511 from garas/improve-authenticate-docs

Update docs for Authentication adapters

src/Auth/BasicAuthenticate.php

@@ -27,27 +27,27 @@ use Cake\Http\ServerRequest;
  *
  * ### Using Basic auth
  *
- * In your controller's components array, add auth + the required config
+ * Load `AuthComponent` in your controller's `initialize()` and add 'Basic' in 'authenticate' key
  * ```
- *  public $components = [
- *      'Auth' => [
- *          'authenticate' => ['Basic']
- *      ]
- *  ];
+ *  $this->loadComponent('Auth', [
+ *      'authenticate' => ['Basic']
+ *      'storage' => 'Memory',
+ *      'unauthorizedRedirect' => false,
+ *  ]);
  * ```
  *
- * You should also set `AuthComponent::$sessionKey = false;` in your AppController's
- * beforeFilter() to prevent CakePHP from sending a session cookie to the client.
+ * You should set `storage` to `Memory` to prevent CakePHP from sending a
+ * session cookie to the client.
  *
- * Since HTTP Basic Authentication is stateless you don't need a login() action
+ * You should set `unauthorizedRedirect` to `false`. This causes `AuthComponent` to
+ * throw a `ForbiddenException` exception instead of redirecting to another page.
+ *
+ * Since HTTP Basic Authentication is stateless you don't need call `setUser()`
  * in your controller. The user credentials will be checked on each request. If
  * valid credentials are not provided, required authentication headers will be sent
  * by this authentication provider which triggers the login dialog in the browser/client.
  *
- * You may also want to use `$this->Auth->unauthorizedRedirect = false;`.
- * By default, unauthorized users are redirected to the referrer URL,
- * `AuthComponent::$loginAction`, or '/'. If unauthorizedRedirect is set to
- * false, a ForbiddenException exception is thrown instead of redirecting.
+ * @see https://book.cakephp.org/3.0/en/controllers/components/authentication.html
  */
 class BasicAuthenticate extends BaseAuthenticate
 {

src/Auth/DigestAuthenticate.php

@@ -25,27 +25,27 @@ use Cake\Utility\Security;
  *
  * ### Using Digest auth
  *
- * In your controller's components array, add auth + the required config
+ * Load `AuthComponent` in your controller's `initialize()` and add 'Digest' in 'authenticate' key
+ *
  * ```
- *  public $components = [
- *      'Auth' => [
- *          'authenticate' => ['Digest']
- *      ]
- *  ];
+ *  $this->loadComponent('Auth', [
+ *      'authenticate' => ['Digest'],
+ *      'storage' => 'Memory',
+ *      'unauthorizedRedirect' => false,
+ *  ]);
  * ```
  *
- * You should also set `AuthComponent::$sessionKey = false;` in your AppController's
- * beforeFilter() to prevent CakePHP from sending a session cookie to the client.
+ * You should set `storage` to `Memory` to prevent CakePHP from sending a
+ * session cookie to the client.
+ *
+ * You should set `unauthorizedRedirect` to `false`. This causes `AuthComponent` to
+ * throw a `ForbiddenException` exception instead of redirecting to another page.
  *
- * Since HTTP Digest Authentication is stateless you don't need a login() action
+ * Since HTTP Digest Authentication is stateless you don't need call `setUser()`
  * in your controller. The user credentials will be checked on each request. If
  * valid credentials are not provided, required authentication headers will be sent
  * by this authentication provider which triggers the login dialog in the browser/client.
  *
- * You may also want to use `$this->Auth->unauthorizedRedirect = false;`.
- * This causes AuthComponent to throw a ForbiddenException exception instead of
- * redirecting to another page.
- *
  * ### Generating passwords compatible with Digest authentication.
  *
  * DigestAuthenticate requires a special password hash that conforms to RFC2617.
@@ -60,6 +60,8 @@ use Cake\Utility\Security;
  * example `User.digest_pass` could be used for a digest password, while
  * `User.password` would store the password hash for use with other methods like
  * Basic or Form.
+ *
+ * @see https://book.cakephp.org/3.0/en/controllers/components/authentication.html
  */
 class DigestAuthenticate extends BasicAuthenticate
 {

src/Auth/FormAuthenticate.php

@@ -19,21 +19,30 @@ use Cake\Http\Response;
 use Cake\Http\ServerRequest;
 
 /**
- * An authentication adapter for AuthComponent. Provides the ability to authenticate using POST
- * data. Can be used by configuring AuthComponent to use it via the AuthComponent::$authenticate config.
+ * Form authentication adapter for AuthComponent.
+ *
+ * Allows you to authenticate users based on form POST data.
+ * Usually, this is a login form that users enter information into.
+ *
+ * ### Using Form auth
+ *
+ * Load `AuthComponent` in your controller's `initialize()` and add 'Form' in 'authenticate' key
  *
  * ```
- *  $this->Auth->authenticate = [
- *      'Form' => [
- *          'finder' => ['auth' => ['some_finder_option' => 'some_value']]
- *      ]
- *  ]
+ * $this->loadComponent('Auth', [
+ *     'authenticate' => [
+ *         'Form' => [
+ *             'fields' => ['username' => 'email', 'password' => 'passwd'],
+ *             'finder' => 'auth',
+ *         ]
+ *     ]
+ * ]);
  * ```
  *
- * When configuring FormAuthenticate you can pass in config to which fields, model and additional conditions
- * are used. See FormAuthenticate::$_config for more information.
+ * When configuring FormAuthenticate you can pass in config to which fields, model and finder
+ * are used. See `BaseAuthenticate::$_defaultConfig` for more information.
  *
- * @see \Cake\Controller\Component\AuthComponent::$authenticate
+ * @see https://book.cakephp.org/3.0/en/controllers/components/authentication.html
  */
 class FormAuthenticate extends BaseAuthenticate
 {