docs: vitepress conversion

.github/workflows/deploy_docs_4x.yml

@@ -21,3 +21,4 @@ jobs:
         with:
           git_remote_url: 'ssh://dokku@apps.cakephp.org:22/authentication-docs-4'
           ssh_private_key: ${{ secrets.DOKKU_SSH_PRIVATE_KEY }}
+          branch: '4.x'

Dockerfile

@@ -1,26 +1,36 @@
-# Basic docker based environment
-# Necessary to trick dokku into building the documentation
-# using dockerfile instead of herokuish
-FROM ubuntu:22.04
-
-# Add basic tools
-RUN apt-get update && \
-  apt-get install -y build-essential \
-    software-properties-common \
-    curl \
-    git \
-    libxml2 \
-    libffi-dev \
-    libssl-dev
-
-# Prevent interactive timezone input
-ENV DEBIAN_FRONTEND=noninteractive
-RUN LC_ALL=C.UTF-8 add-apt-repository ppa:ondrej/php && \
-  apt-get update && \
-  apt-get install -y php8.1-cli php8.1-mbstring php8.1-xml php8.1-zip php8.1-intl php8.1-opcache php8.1-sqlite
-
-WORKDIR /code
-
-VOLUME ["/code"]
-
-CMD [ '/bin/bash' ]
+# ----------------------
+# 1. Build stage
+# ----------------------
+FROM node:22-alpine AS builder
+
+# Git is required because docs/package.json pulls a dependency from GitHub.
+RUN apk add --no-cache git openssh-client
+
+WORKDIR /app/docs
+
+# Copy dependency manifests first to preserve Docker layer caching.
+COPY docs/ ./
+RUN npm ci
+
+# Increase max-old-space-size to avoid memory issues during build
+ENV NODE_OPTIONS="--max-old-space-size=8192"
+
+# Build the site.
+RUN npm run docs:build
+
+# ----------------------
+# 2. Runtime stage (nginx)
+# ----------------------
+FROM nginx:1.27-alpine AS runner
+
+# Copy built files
+COPY --from=builder /app/docs/.vitepress/dist /usr/share/nginx/html
+
+# Expose port
+EXPOSE 80
+
+# Health check (optional)
+HEALTHCHECK CMD wget --quiet --tries=1 --spider http://localhost:80/ || exit 1
+
+# Start nginx
+CMD ["nginx", "-g", "daemon off;"]

docs/.gitignore

@@ -0,0 +1,4 @@
+node_modules
+*/public/
+.vitepress/cache
+.vitepress/dist

docs/.vitepress/config.js

@@ -0,0 +1,50 @@
+import baseConfig from '@cakephp/docs-skeleton/config'
+
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+const toc_en = require("./toc_en.json");
+
+const versions = {
+  text: "4.x",
+  items: [
+    { text: "4.x (current)", link: "https://book.cakephp.org/authentication/4/en/", target: '_self' },
+    { text: "3.x", link: "https://book.cakephp.org/authentication/3/en/", target: '_self' },
+    { text: "2.x", link: "https://book.cakephp.org/authentication/2/en/", target: '_self' },
+  ],
+};
+
+// This file contains overrides for .vitepress/config.js
+export default {
+  extends: baseConfig,
+  srcDir: 'en',
+  title: 'Authentication plugin',
+  description: 'Authentication - CakePHP Authentication Plugin Documentation',
+  base: "/authentication/4/en/",
+  rewrites: {
+    "en/:slug*": ":slug*",
+  },
+  sitemap: {
+    hostname: "https://book.cakephp.org/authentication/4/en/",
+  },
+  themeConfig: {
+    socialLinks: [
+      { icon: "github", link: "https://github.com/cakephp/authentication" },
+    ],
+    editLink: {
+      pattern: "https://github.com/cakephp/authentication/edit/4.x/docs/:path",
+      text: "Edit this page on GitHub",
+    },
+    sidebar: toc_en,
+    nav: [
+      { text: "CakePHP Book", link: "https://book.cakephp.org/" },
+      { ...versions },
+    ],
+  },
+  substitutions: {},
+  locales: {
+    root: {
+      label: "English",
+      lang: "en",
+    },
+  },
+};

docs/.vitepress/theme/index.js

@@ -0,0 +1 @@
+export { default } from '@cakephp/docs-skeleton'

docs/.vitepress/toc_en.json

@@ -0,0 +1,49 @@
+{
+  "/": [
+    {
+      "text": "Getting Started",
+      "collapsed": false,
+      "items": [
+        { "text": "Quick Start", "link": "/index" }
+      ]
+    },
+    {
+      "text": "Core Concepts",
+      "collapsed": false,
+      "items": [
+        { "text": "Authenticators", "link": "/authenticators" },
+        { "text": "Identifiers", "link": "/identifiers" },
+        { "text": "Identity Object", "link": "/identity-object" },
+        { "text": "Password Hashers", "link": "/password-hashers" }
+      ]
+    },
+    {
+      "text": "Integration",
+      "collapsed": false,
+      "items": [
+        { "text": "Middleware", "link": "/middleware" },
+        { "text": "Authentication Component", "link": "/authentication-component" },
+        { "text": "View Helper", "link": "/view-helper" },
+        { "text": "Testing", "link": "/testing" }
+      ]
+    },
+    {
+      "text": "Advanced Topics",
+      "collapsed": true,
+      "items": [
+        { "text": "User Impersonation", "link": "/impersonation" },
+        { "text": "Redirect Validation", "link": "/redirect-validation" },
+        { "text": "URL Checkers", "link": "/url-checkers" },
+        { "text": "Migration from the AuthComponent", "link": "/migration-from-the-authcomponent" }
+      ]
+    },
+    {
+      "text": "Upgrade Guides",
+      "collapsed": true,
+      "items": [
+        { "text": "Upgrading from 2.x to 3.x", "link": "/upgrade-2-to-3" },
+        { "text": "Upgrading from 3.x to 4.x", "link": "/upgrade-3-to-4" }
+      ]
+    }
+  ]
+}

docs/en/authentication-component.md

@@ -0,0 +1,123 @@
+# Authentication Component
+
+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
+$this->loadComponent('Authentication.Authentication', [
+    'logoutRedirect' => '/users/login'  // Default is false
+]);
+```
+
+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
+// In your controller's beforeFilter method.
+$this->Authentication->allowUnauthenticated(['view']);
+```
+
+## Accessing the logged in user
+
+You can get the authenticated user identity data using the authentication
+component:
+
+``` php
+$user = $this->Authentication->getIdentity();
+```
+
+You can also get the identity directly from the request instance:
+
+``` php
+$user = $request->getAttribute('identity');
+```
+
+## Checking the login status
+
+You can check if the authentication process was successful by accessing the
+result object:
+
+``` php
+// Using Authentication component
+$result = $this->Authentication->getResult();
+
+// Using request object
+$result = $request->getAttribute('authentication')->getResult();
+
+if ($result->isValid()) {
+    $user = $request->getAttribute('identity');
+} else {
+    $this->log($result->getStatus());
+    $this->log($result->getErrors());
+}
+```
+
+The result sets objects status returned from `getStatus()` will match one of
+these constants in the Result object:
+
+- `ResultInterface::SUCCESS`, when successful.
+- `ResultInterface::FAILURE_IDENTITY_NOT_FOUND`, when identity could not be found.
+- `ResultInterface::FAILURE_CREDENTIALS_INVALID`, when credentials are invalid.
+- `ResultInterface::FAILURE_CREDENTIALS_MISSING`, when credentials are missing in the request.
+- `ResultInterface::FAILURE_OTHER`, on any other kind of failure.
+
+The error array returned by `getErrors()` contains **additional** information
+coming from the specific system against which the authentication attempt was
+made. For example LDAP or OAuth would put errors specific to their
+implementation in here for easier logging and debugging the cause. But most of
+the included authenticators don't put anything in here.
+
+## Logging out the identity
+
+To log an identity out just do:
+
+``` php
+$this->Authentication->logout();
+```
+
+If you have set the `logoutRedirect` config, `Authentication::logout()` will
+return that value else will return `false`. It won't perform any actual redirection
+in either case.
+
+Alternatively, instead of the component you can also use the service to log out:
+
+``` php
+$return = $request->getAttribute('authentication')->clearIdentity($request, $response);
+```
+
+The result returned will contain an array like this:
+
+``` php
+[
+    'response' => object(Cake\Http\Response) { ... },
+    'request' => object(Cake\Http\ServerRequest) { ... },
+]
+```
+
+> [!NOTE]
+> This will return an array containing the request and response
+> objects. Since both are immutable you'll get new objects back. Depending on your
+> context you're working in you'll have to use these instances from now on if you
+> want to continue to work with the modified response and request objects.
+
+## Configure Automatic Identity Checks
+
+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
+// In your controller's initialize() method.
+$this->loadComponent('Authentication.Authentication', [
+    'identityCheckEvent' => 'Controller.initialize',
+]);
+```
+
+You can also disable identity checks entirely with the `requireIdentity`
+option or by calling `disableIdentityCheck` from the controller's `beforeFilter()` method itself:
+
+``` php
+$this->Authentication->disableIdentityCheck();
+```