Merge branch '5.x' of github.com:cakephp/docs into 5.x

Author: LordSimal

.github/workflows/docs-validation.yml

@@ -48,6 +48,17 @@ jobs:
             echo "✅ Valid: $file"
           done
 
+  toc-link-check:
+    name: Validate TOC Links
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Check TOC links exist
+        run: node bin/check-toc-links.js
+
   markdown-lint:
     name: Lint Markdown
     runs-on: ubuntu-latest

bin/check-toc-links.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+
+/**
+ * TOC Link Validator
+ *
+ * Validates that all links in toc_*.json files point to existing markdown files.
+ *
+ * Usage:
+ *   node bin/check-toc-links.js
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Recursively extract all links from TOC items
+ */
+function extractLinks(items, links = []) {
+  for (const item of items) {
+    if (item.link && !item.link.startsWith("http")) {
+      links.push(item.link);
+    }
+    if (item.items) {
+      extractLinks(item.items, links);
+    }
+  }
+  return links;
+}
+
+/**
+ * Check if a TOC link resolves to an existing file
+ */
+function checkLink(link, docsDir, lang) {
+  // TOC links may include language prefix: "/ja/quickstart" or just "/quickstart"
+  // Strip the language prefix if present
+  let relativePath = link.startsWith("/") ? link.slice(1) : link;
+
+  // Remove language prefix if link starts with it (e.g., "ja/quickstart" -> "quickstart")
+  const langPrefix = lang + "/";
+  if (relativePath.startsWith(langPrefix)) {
+    relativePath = relativePath.slice(langPrefix.length);
+  }
+
+  const filePath = path.join(docsDir, relativePath + ".md");
+
+  return fs.existsSync(filePath);
+}
+
+/**
+ * Extract language code from TOC filename
+ * e.g., "toc_en.json" -> "en"
+ */
+function getLangFromTocFile(tocFile) {
+  const match = tocFile.match(/^toc_(\w+)\.json$/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Main validation function
+ */
+function validateTocFiles() {
+  const tocFiles = fs.readdirSync(".").filter((f) => f.match(/^toc_.*\.json$/));
+
+  if (tocFiles.length === 0) {
+    console.error("No toc_*.json files found");
+    process.exit(1);
+  }
+
+  let hasErrors = false;
+
+  for (const tocFile of tocFiles) {
+    const lang = getLangFromTocFile(tocFile);
+    if (!lang) {
+      console.error(`Could not extract language from ${tocFile}`);
+      continue;
+    }
+
+    const docsDir = path.join("docs", lang);
+    if (!fs.existsSync(docsDir)) {
+      console.error(`Docs directory not found: ${docsDir}`);
+      hasErrors = true;
+      continue;
+    }
+
+    console.log(`Checking ${tocFile} against ${docsDir}/...`);
+
+    const content = fs.readFileSync(tocFile, "utf8");
+    const toc = JSON.parse(content);
+
+    // TOC structure has keys like "/" with arrays of items
+    const allLinks = [];
+    for (const key of Object.keys(toc)) {
+      extractLinks(toc[key], allLinks);
+    }
+
+    const missingFiles = [];
+    for (const link of allLinks) {
+      if (!checkLink(link, docsDir, lang)) {
+        missingFiles.push(link);
+      }
+    }
+
+    if (missingFiles.length > 0) {
+      hasErrors = true;
+      console.error(`\n✗ ${tocFile}: ${missingFiles.length} broken link(s)\n`);
+      for (const link of missingFiles) {
+        // Calculate expected path (strip lang prefix if present)
+        let relativePath = link.startsWith("/") ? link.slice(1) : link;
+        const langPrefix = lang + "/";
+        if (relativePath.startsWith(langPrefix)) {
+          relativePath = relativePath.slice(langPrefix.length);
+        }
+        const expectedPath = path.join(docsDir, relativePath + ".md");
+        console.error(`  ${link}`);
+        console.error(`    Expected: ${expectedPath}`);
+      }
+      console.error("");
+    } else {
+      console.log(`✓ ${tocFile}: ${allLinks.length} link(s) valid\n`);
+    }
+  }
+
+  if (hasErrors) {
+    console.error("TOC validation failed");
+    process.exit(1);
+  }
+
+  console.log("✓ All TOC links are valid!");
+}
+
+validateTocFiles();

docs/en/contributing/cakephp-coding-conventions.md

@@ -411,40 +411,18 @@ be preceded by a newline.
 
 Variable types for use in DocBlocks:
 
-Type
-Description
-
-mixed
-A variable with undefined (or multiple) type.
-
-int
-Integer type variable (whole number).
-
-float
-Float type (point number).
-
-bool
-Logical type (true or false).
-
-string
-String type (any value in " " or ' ').
-
-null
-Null type. Usually used in conjunction with another type.
-
-array
-Array type.
-
-object
-Object type. A specific class name should be used if possible.
-
-resource
-Resource type (returned by for example mysql_connect()).
-Remember that when you specify the type as mixed, you should indicate
-whether it is unknown, or what the possible types are.
-
-callable
-Callable function.
+| Type | Description |
+|------|-------------|
+| mixed | A variable with undefined (or multiple) type. |
+| int | Integer type variable (whole number). |
+| float | Float type (point number). |
+| bool | Logical type (true or false). |
+| string | String type (any value in " " or ' '). |
+| null | Null type. Usually used in conjunction with another type. |
+| array | Array type. |
+| object | Object type. A specific class name should be used if possible. |
+| resource | Resource type (returned by for example mysql_connect()). Remember that when you specify the type as mixed, you should indicate whether it is unknown, or what the possible types are. |
+| callable | Callable function. |
 
 You can also combine types using the pipe char:
 

docs/en/controllers/request-response.md

@@ -782,12 +782,12 @@ $response = $this->response->withFile(
 The supported options are:
 
 name
-The name allows you to specify an alternate file name to be sent to
-the user.
+: The name allows you to specify an alternate file name to be sent to
+  the user.
 
 download
-A boolean value indicating whether headers should be set to force
-download.
+: A boolean value indicating whether headers should be set to force
+  download.
 
 ### Sending a String as a File
 

docs/en/core-libraries/logging.md

@@ -467,7 +467,7 @@ more information.
 `static` Cake\\Log\\Log::**configured**(): array
 
 returns
-An array of configured loggers.
+: An array of configured loggers.
 
 Get the names of the configured loggers.
 

docs/en/development/configuration.md

@@ -87,11 +87,11 @@ Below is a description of the variables and how they affect your CakePHP
 application.
 
 debug
-Changes CakePHP debugging output. `false` = Production mode. No error
-messages, errors, or warnings shown. `true` = Errors and warnings shown.
+: Changes CakePHP debugging output. `false` = Production mode. No error
+  messages, errors, or warnings shown. `true` = Errors and warnings shown.
 
 App.namespace
-The namespace to find app classes under.
+: The namespace to find app classes under.
 
 > [!NOTE]
 > When changing the namespace in your configuration, you will also
@@ -102,78 +102,77 @@ The namespace to find app classes under.
 <div id="core-configuration-baseurl">
 
 App.baseUrl
-Un-comment this definition if you **don’t** plan to use Apache’s
-mod_rewrite with CakePHP. Don’t forget to remove your .htaccess
-files too.
+: Un-comment this definition if you **don't** plan to use Apache's
+  mod_rewrite with CakePHP. Don't forget to remove your .htaccess
+  files too.
 
 App.base
-The base directory the app resides in. If `false` this
-will be auto detected. If not `false`, ensure your string starts
-with a `/` and does NOT end with a `/`. For example, `/basedir` is a valid
-App.base.
+: The base directory the app resides in. If `false` this
+  will be auto detected. If not `false`, ensure your string starts
+  with a `/` and does NOT end with a `/`. For example, `/basedir` is a valid
+  App.base.
 
 App.encoding
-Define what encoding your application uses. This encoding
-is used to generate the charset in the layout, and encode entities.
-It should match the encoding values specified for your database.
+: Define what encoding your application uses. This encoding
+  is used to generate the charset in the layout, and encode entities.
+  It should match the encoding values specified for your database.
 
 App.webroot
-The webroot directory.
+: The webroot directory.
 
 App.wwwRoot
-The file path to webroot.
+: The file path to webroot.
 
 App.fullBaseUrl
-The fully qualified domain name (including protocol) to your application's
-root. This is used when generating absolute URLs. By default, this value
-is generated using the `$_SERVER` environment. However, you should define it
-manually to optimize performance or if you are concerned about people
-manipulating the `Host` header.
-In a CLI context (from command) the `fullBaseUrl` cannot be read from $_SERVER,
-as there is no webserver involved. You do need to specify it yourself if
-you do need to generate URLs from a shell (for example, when sending emails).
+: The fully qualified domain name (including protocol) to your application's
+  root. This is used when generating absolute URLs. By default, this value
+  is generated using the `$_SERVER` environment. However, you should define it
+  manually to optimize performance or if you are concerned about people
+  manipulating the `Host` header.
+  In a CLI context (from command) the `fullBaseUrl` cannot be read from $_SERVER,
+  as there is no webserver involved. You do need to specify it yourself if
+  you do need to generate URLs from a shell (for example, when sending emails).
 
 App.imageBaseUrl
-Web path to the public images directory under webroot. If you are using
-a `CDN` you should set this value to the CDN's location.
+: Web path to the public images directory under webroot. If you are using
+  a `CDN` you should set this value to the CDN's location.
 
 App.cssBaseUrl
-Web path to the public css directory under webroot. If you are using
-a `CDN` you should set this value to the CDN's location.
+: Web path to the public css directory under webroot. If you are using
+  a `CDN` you should set this value to the CDN's location.
 
 App.jsBaseUrl
-Web path to the public js directory under webroot. If you are using
-a `CDN` you should set this value to the CDN's location.
+: Web path to the public js directory under webroot. If you are using
+  a `CDN` you should set this value to the CDN's location.
 
 App.paths
-Configure paths for non class based resources. Supports the
-`plugins`, `templates`, `locales` subkeys, which allow the definition
-of paths for plugins, view templates and locale files respectively.
+: Configure paths for non class based resources. Supports the
+  `plugins`, `templates`, `locales` subkeys, which allow the definition
+  of paths for plugins, view templates and locale files respectively.
 
 App.uploadedFilesAsObjects
-Defines whether uploaded files are being represented as objects (`true`),
-or arrays (`false`). This option is being treated as enabled by default.
-See the [File Uploads section](../controllers/request-response#request-file-uploads) in the Request &
-Response Objects chapter for more information.
+: Defines whether uploaded files are being represented as objects (`true`),
+  or arrays (`false`). This option is being treated as enabled by default.
+  See the [File Uploads section](../controllers/request-response#request-file-uploads) in the Request &
+  Response Objects chapter for more information.
 
 Security.salt
-A random string used in hashing. This value is also used as the
-HMAC salt when doing symmetric encryption.
+: A random string used in hashing. This value is also used as the
+  HMAC salt when doing symmetric encryption.
 
 Asset.timestamp
-Appends a timestamp which is last modified time of the particular
-file at the end of asset files URLs (CSS, JavaScript, Image) when
-using proper helpers. Valid values:
-
-- (bool) `false` - Doesn't do anything (default)
-- (bool) `true` - Appends the timestamp when debug is `true`
-- (string) 'force' - Always appends the timestamp.
+: Appends a timestamp which is last modified time of the particular
+  file at the end of asset files URLs (CSS, JavaScript, Image) when
+  using proper helpers. Valid values:
+  (bool) `false` - Doesn't do anything (default),
+  (bool) `true` - Appends the timestamp when debug is `true`,
+  (string) 'force' - Always appends the timestamp.
 
 Asset.cacheTime
-Sets the asset cache time. This determines the http header `Cache-Control`'s
-`max-age`, and the http header's `Expire`'s time for assets.
-This can take anything that you version of PHP's [strtotime function](https://php.net/manual/en/function.strtotime.php) can take.
-The default is `+1 day`.
+: Sets the asset cache time. This determines the http header `Cache-Control`'s
+  `max-age`, and the http header's `Expire`'s time for assets.
+  This can take anything that you version of PHP's [strtotime function](https://php.net/manual/en/function.strtotime.php) can take.
+  The default is `+1 day`.
 
 </div>
 

docs/en/index.md

@@ -40,7 +40,7 @@ Get a CakePHP application running in under 5 minutes:
 
 ```bash [Composer]
 # Create new project
-composer create-project --prefer-dist cakephp/app:~5.0 my_app
+composer create-project --prefer-dist cakephp/app:|cakeversion| my_app
 
 # Start development server
 cd my_app
@@ -53,14 +53,14 @@ bin/cake server
 # Setup with DDEV
 mkdir my-cakephp-app && cd my-cakephp-app
 ddev config --project-type=cakephp --docroot=webroot
-ddev composer create --prefer-dist cakephp/app:~5.0
+ddev composer create --prefer-dist cakephp/app:|cakeversion|
 ddev launch
 ```
 
 ```bash [Docker]
 # Using official PHP image
 docker run -it --rm -v $(pwd):/app composer create-project \
-  --prefer-dist cakephp/app:~5.0 my_app
+  --prefer-dist cakephp/app:|cakeversion| my_app
 
 cd my_app
 docker run -it --rm -p 8765:8765 -v $(pwd):/app \