Merge pull request #779 from cakephp/doc-validation-workflow

Add doc validation workflow + fix linting errors

Author: josbeir

.github/workflows/docs-validation.yml

@@ -0,0 +1,27 @@
+name: Documentation Validation
+
+on:
+  push:
+    branches:
+      - 4.x
+    paths:
+      - 'docs/**'
+      - '.github/**'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/**'
+
+jobs:
+  validate:
+    uses: cakephp/.github/.github/workflows/docs-validation.yml@doc-workflows
+    with:
+      docs-path: 'docs'
+      vitepress-path: 'docs/.vitepress'
+      enable-config-js-check: true
+      enable-json-lint: true
+      enable-toc-check: true
+      enable-spell-check: true
+      enable-markdown-lint: true
+      enable-link-check: true
+      tools-ref: 'doc-workflows'

docs/en/authentication-component.md

@@ -4,7 +4,7 @@ You can use the `AuthenticationComponent` to access the result of
 authentication, get user identity and logout user. Load the component in your
 `AppController::initialize()` like any other component:
 
-``` php
+```php
 $this->loadComponent('Authentication.Authentication', [
     'logoutRedirect' => '/users/login'  // Default is false
 ]);
@@ -14,7 +14,7 @@ Once loaded, the `AuthenticationComponent` will require that all actions have an
 authenticated user present, but perform no other access control checks. You can
 disable this check for specific actions using `allowUnauthenticated()`:
 
-``` php
+```php
 // In your controller's beforeFilter method.
 $this->Authentication->allowUnauthenticated(['view']);
 ```
@@ -24,13 +24,13 @@ $this->Authentication->allowUnauthenticated(['view']);
 You can get the authenticated user identity data using the authentication
 component:
 
-``` php
+```php
 $user = $this->Authentication->getIdentity();
 ```
 
 You can also get the identity directly from the request instance:
 
-``` php
+```php
 $user = $request->getAttribute('identity');
 ```
 
@@ -39,7 +39,7 @@ $user = $request->getAttribute('identity');
 You can check if the authentication process was successful by accessing the
 result object:
 
-``` php
+```php
 // Using Authentication component
 $result = $this->Authentication->getResult();
 
@@ -73,7 +73,7 @@ the included authenticators don't put anything in here.
 
 To log an identity out just do:
 
-``` php
+```php
 $this->Authentication->logout();
 ```
 
@@ -83,13 +83,13 @@ in either case.
 
 Alternatively, instead of the component you can also use the service to log out:
 
-``` php
+```php
 $return = $request->getAttribute('authentication')->clearIdentity($request, $response);
 ```
 
 The result returned will contain an array like this:
 
-``` php
+```php
 [
     'response' => object(Cake\Http\Response) { ... },
     'request' => object(Cake\Http\ServerRequest) { ... },
@@ -108,7 +108,7 @@ By default `AuthenticationComponent` will automatically enforce an identity to
 be present during the `Controller.startup` event. You can have this check
 applied during the `Controller.initialize` event instead:
 
-``` php
+```php
 // In your controller's initialize() method.
 $this->loadComponent('Authentication.Authentication', [
     'identityCheckEvent' => 'Controller.initialize',
@@ -118,6 +118,6 @@ $this->loadComponent('Authentication.Authentication', [
 You can also disable identity checks entirely with the `requireIdentity`
 option or by calling `disableIdentityCheck` from the controller's `beforeFilter()` method itself:
 
-``` php
+```php
 $this->Authentication->disableIdentityCheck();
 ```

docs/en/authenticators.md

@@ -30,7 +30,7 @@ With only the ID stored, the invalidation due to objects being modified will als
 A default `TokenIdentifier` is provided that looks up users by their `id` field,
 so minimal configuration is required:
 
-``` php
+```php
 $service->loadAuthenticator('Authentication.PrimaryKeySession');
 ```
 
@@ -43,15 +43,15 @@ Configuration options:
 For custom lookup fields, the `idField` and `identifierKey` options propagate
 to the default identifier automatically:
 
-``` php
+```php
 $service->loadAuthenticator('Authentication.PrimaryKeySession', [
     'idField' => 'uuid',
 ]);
 ```
 
 You can also provide a fully custom identifier configuration if needed:
 
-``` php
+```php
 $service->loadAuthenticator('Authentication.PrimaryKeySession', [
     'identifier' => [
         'Authentication.Token' => [
@@ -109,7 +109,7 @@ Configuration options:
 
 An example of getting a token from a header, or query string would be:
 
-``` php
+```php
 $service->loadAuthenticator('Authentication.Token', [
     'queryParam' => 'token',
     'header' => 'Authorization',
@@ -122,7 +122,7 @@ as long as the token was preceded by `Token` and a space.
 
 The token will always be passed to the configured identifier as follows:
 
-``` php
+```php
 [
     'token' => '{token-value}',
 ]
@@ -158,7 +158,7 @@ the value of `Cake\Utility\Security::salt()` as encryption key.
 For enhanced security one can instead use the `RS256` asymmetric key algorithm.
 You can generate the required keys for that as follows:
 
-``` text
+```text
 # generate private key
 openssl genrsa -out config/jwt.key 1024
 # generate public key
@@ -175,7 +175,7 @@ for token verification.
 
 Add the following to your `Application` class:
 
-``` php
+```php
 public function getAuthenticationService(ServerRequestInterface $request): AuthenticationServiceInterface
 {
     $service = new AuthenticationService();
@@ -193,7 +193,7 @@ public function getAuthenticationService(ServerRequestInterface $request): Authe
 
 In your `UsersController`:
 
-``` php
+```php
 use Firebase\JWT\JWT;
 
 public function login(): void
@@ -221,7 +221,7 @@ public function login(): void
 
 Using a JWKS fetched from an external JWKS endpoint is supported as well:
 
-``` php
+```php
 // Application.php
 public function getAuthenticationService(ServerRequestInterface $request): AuthenticationServiceInterface
 {
@@ -257,7 +257,7 @@ prepared to handle signing key rotations.
 Beside from sharing the public key file to external application, you can
 distribute it via a JWKS endpoint by configuring your app as follows:
 
-``` php
+```php
 // config/routes.php
 $builder->setExtensions('json');
 $builder->connect('/.well-known/{controller}', [
@@ -375,7 +375,7 @@ after their session expires for as long as the cookie is valid. If a user is
 explicitly logged out via `AuthenticationComponent::logout()` the
 authentication cookie is **also destroyed**. An example configuration would be:
 
-``` php
+```php
 // In Application::getAuthenticationService()
 
 // Reuse fields in multiple authenticators.
@@ -404,7 +404,7 @@ $service->loadAuthenticator('Authentication.Cookie', [
 
 You'll also need to add a checkbox to your login form to have cookies created:
 
-``` php
+```php
 // In your login view
 <?= $this->Form->control('remember_me', ['type' => 'checkbox']);
 ```
@@ -420,7 +420,7 @@ environment variables exposed by the webserver. This enables authentication via
 [Shibboleth](https://shibboleth.atlassian.net/wiki/spaces/CONCEPT/overview)
 and similar SAML 1.1 implementations. An example configuration is:
 
-``` php
+```php
 // Configure a token identifier that maps `USER_ID` to the
 // username column
 $identifier = [
@@ -442,7 +442,6 @@ $service->loadAuthenticator('Authentication.Environment', [
 ]);
 ```
 
-
 ## Events
 
 There is only one event that is fired by authentication:
@@ -505,7 +504,7 @@ page](url-checkers).
 After a user has been authenticated you may want to inspect or interact with the
 Authenticator that successfully authenticated the user:
 
-``` php
+```php
 // In a controller action
 $service = $this->request->getAttribute('authentication');
 
@@ -515,7 +514,7 @@ $authenticator = $service->getAuthenticationProvider();
 
 You can also get the identifier that identified the user as well:
 
-``` php
+```php
 // In a controller action
 $service = $this->request->getAttribute('authentication');
 
@@ -530,7 +529,7 @@ you should remember that these authenticators will halt the request when
 authentication credentials are missing or invalid. This is necessary as these
 authenticators must send specific challenge headers in the response:
 
-``` php
+```php
 use Authentication\AuthenticationService;
 
 // Instantiate the service
@@ -569,7 +568,7 @@ authenticated. You can convert this exception into a redirect using the
 You can also pass the current request target URI as a query parameter
 using the `queryParam` option:
 
-``` php
+```php
 // In the getAuthenticationService() method of your src/Application.php
 
 $service = new AuthenticationService();
@@ -584,7 +583,7 @@ $service->setConfig([
 Then in your controller's login method you can use `getLoginRedirect()` to get
 the redirect target safely from the query string parameter:
 
-``` php
+```php
 public function login(): ?\Cake\Http\Response
 {
     $result = $this->Authentication->getResult();
@@ -613,7 +612,7 @@ authentication for your API, but sessions for your web interface. To support
 this flow you can return different authentication services based on the URL
 path, or any other request attribute:
 
-``` php
+```php
 public function getAuthenticationService(
     ServerRequestInterface $request
 ): AuthenticationServiceInterface {

docs/en/contents.md

@@ -1,6 +1,6 @@
 # Contents
 
-### CakePHP Authentication
+## CakePHP Authentication
 
 - [Quick Start](index)
 - [Authenticators](authenticators)

docs/en/identifiers.md

@@ -4,7 +4,7 @@ Identifiers will identify a user or service based on the information
 that was extracted from the request by the authenticators. A holistic example of
 using the Password Identifier looks like:
 
-``` php
+```php
 $identifier = [
     'Authentication.Password' => [
         'fields' => [
@@ -118,7 +118,7 @@ Configuration options:
 
 Callback identifiers can either return `null|ArrayAccess` for simple results, or an `Authentication\Authenticator\Result` if you want to forward error messages:
 
-``` php
+```php
 // A simple callback identifier
 $identifier = [
     'Authentication.Callback' => [
@@ -185,7 +185,7 @@ reside under `App\Identifier\Resolver` namespace.
 
 Resolver can be configured using `resolver` config option:
 
-``` php
+```php
 $identifier = [
     'Authentication.Password' => [
         'resolver' => [
@@ -200,7 +200,7 @@ $identifier = [
 
 Or pass the constructed resolver directly into the identifier configuration:
 
-``` php
+```php
 $resolver = new \App\Identifier\Resolver\CustomResolver();
 $identifier = [
     'Authentication.Password' => [

docs/en/identity-object.md

@@ -7,7 +7,7 @@ called to get the primary id value of the current log in identity.
 The reason this object exists is to provide an interface that makes it
 implementations/sources:
 
-``` php
+```php
 // Service
 $authenticationService
     ->getIdentity()
@@ -28,7 +28,7 @@ The identity object provides ArrayAccess but as well a `get()` method to
 access data. It is strongly recommended to use the `get()` method over array
 access because the get method is aware of the field mapping:
 
-``` php
+```php
 $identity->get('email');
 $identity->get('username');
 ```
@@ -38,7 +38,7 @@ The `get()` method can also be type-hinted via IDE meta file, e.g. through
 
 If you want, you can use property access, however:
 
-``` text
+```text
 $identity->email;
 $identity->username;
 ```
@@ -48,7 +48,7 @@ is pretty useful if the identifier of the identity is a non-conventional
 `id` field or if you want to map other fields to more generic and
 common names:
 
-``` php
+```php
 $identity = new Identity($data, [
     'fieldMap' => [
         'id' => 'uid',
@@ -69,7 +69,7 @@ create your own identity object, your object must implement the
 If you’d like to continue using your existing User class with this
 plugin you can implement the `Authentication\IdentityInterface`:
 
-``` php
+```php
 namespace App\Model\Entity;
 
 use Authentication\IdentityInterface;
@@ -103,7 +103,7 @@ If your identifiers cannot have their resulting objects modified to
 implement the `IdentityInterface` you can implement a custom decorator
 that implements the required interface:
 
-``` php
+```php
 // You can use a callable...
 $identityResolver = function ($data) {
     return new MyCustomIdentity($data);