Merge branch '5.next' into 6.x

Author: josbeir

.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/appendices/5-4-migration-guide.md

@@ -0,0 +1,72 @@
+# 5.4 Migration Guide
+
+The 5.4.0 release is backwards compatible with 5.0. It adds new functionality
+and introduces new deprecations. Any functionality deprecated in 5.x will be
+removed in 6.0.0.
+
+## Upgrade Tool
+
+The [upgrade tool](../appendices/migration-guides) provides rector rules for
+automating some of the migration work. Run rector before updating your
+`composer.json` dependencies:
+
+```text
+bin/cake upgrade rector --rules cakephp54 <path/to/app/src>
+```
+
+## Behavior Changes
+
+### I18n
+
+`Number::parseFloat()` now returns `null` instead of `0.0` when parsing
+fails. This also affects `FloatType` and `DecimalType` database types.
+
+### ORM
+
+The default eager loading strategy for `HasMany` and `BelongsToMany` associations
+has changed from `select` to `subquery`. If you need the previous behavior,
+explicitly set `'strategy' => 'select'` when defining associations.
+
+## Deprecations
+
+- WIP
+
+## New Features
+
+### Controller
+
+- Added `#[RequestToDto]` attribute for automatic mapping of request data to
+  Data Transfer Objects in controller actions.
+  See [Request to DTO Mapping](../development/dependency-injection#request-to-dto-mapping).
+- Added `unlockActions()` and `unlockFields()` convenience methods to
+  `FormProtectionComponent`.
+  See [Form Protection Component](../controllers/components/form-protection).
+
+### Database
+
+- Added `notBetween()` method for `NOT BETWEEN` expressions.
+  See [Query Builder](../orm/query-builder#advanced-conditions).
+- Added `inOrNull()` and `notInOrNull()` methods for combining `IN` conditions with `IS NULL`.
+- Added `isDistinctFrom()` and `isNotDistinctFrom()` methods for null-safe comparisons.
+
+### I18n
+
+- `Number::toReadableSize()` now uses decimal units (KB = 1000 bytes) by default.
+  Binary units (KiB = 1024 bytes) can be enabled via parameter or `Number::setUseIecUnits()`.
+
+### ORM
+
+- The `associated` option in `newEntity()` and `patchEntity()` now supports
+  nested array format matching `contain()` syntax.
+  See [Converting Request Data into Entities](../orm/saving-data#converting-request-data-into-entities).
+
+### Utility
+
+- Added `Cake\Utility\Fs\Finder` class for fluent file discovery with pattern matching,
+  depth control, and custom filters. Added `Cake\Utility\Fs\Path` for cross-platform
+  path manipulation.
+
+### View
+
+- Added `{{inputId}}` template variable to `inputContainer` and `error` templates
+  in FormHelper. See [Built-in Template Variables](../views/helpers/form#built-in-template-variables).

docs/en/console-commands/commands.md

@@ -37,8 +37,8 @@ class HelloCommand extends Command
 ```
 
 Command classes must implement an `execute()` method that does the bulk of
-their work. This method is called when a command is invoked. Let's call our first
-command application directory, run:
+their work. This method is called when a command is invoked. Let's call our
+first command. From your application directory, run:
 
 ```bash
 bin/cake hello
@@ -48,6 +48,16 @@ You should see the following output:
 
     Hello world.
 
+::: info
+The `Arguments` and `ConsoleIo` instances passed to `execute()` are also
+available on the command instance as `$this->args` and `$this->io`.
+In 6.x, the `execute()` method signature will drop these arguments
+and `$this->args` / `$this->io` will be the only way to access
+these objects. See the
+[6.x command refactor](https://github.com/cakephp/cakephp/pull/18983) for
+details.
+:::
+
 Our `execute()` method isn't very interesting let's read some input from the
 command line:
 

docs/en/console-commands/input-output.md

@@ -182,6 +182,84 @@ $io->helper('Banner')
 The `BannerHelper` was added in 5.1
 :::
 
+### Tree Helper
+
+The `TreeHelper` formats nested arrays into a tree structure with visual
+connectors, similar to the output of the Unix `tree` command. This is useful
+for displaying hierarchical data such as directory structures, menu trees,
+or nested categories:
+
+```php
+$data = [
+    'src' => [
+        'Controller' => [
+            'AppController.php',
+            'UsersController.php',
+        ],
+        'Model' => [
+            'Entity' => [
+                'User.php',
+            ],
+            'Table' => [
+                'UsersTable.php',
+            ],
+        ],
+    ],
+    'config' => [
+        'app.php',
+        'routes.php',
+    ],
+];
+$io->helper('Tree')->output($data);
+
+// Outputs:
+// ├── src
+// │   ├── Controller
+// │   │   ├── AppController.php
+// │   │   └── UsersController.php
+// │   └── Model
+// │       ├── Entity
+// │       │   └── User.php
+// │       └── Table
+// │           └── UsersTable.php
+// └── config
+//     ├── app.php
+//     └── routes.php
+```
+
+The helper supports various value types including strings, booleans, enums,
+and closures for lazy evaluation:
+
+```php
+$data = [
+    'debug' => true,
+    'cache' => false,
+    'status' => fn () => 'computed value',
+];
+$io->helper('Tree')->output($data);
+
+// Outputs:
+// ├── debug
+// │   └── true
+// ├── cache
+// │   └── false
+// └── status
+//     └── computed value
+```
+
+You can customize the indentation using the `baseIndent` and `elementIndent`
+configuration options:
+
+```php
+$io->helper('Tree')
+    ->setConfig('baseIndent', 4)
+    ->output($data);
+```
+
+::: info Added in version 5.3.0
+The `TreeHelper` was added in 5.3
+:::
+
 ## Getting User Input
 
 `method` Cake\\Console\\ConsoleIo::**ask**(string $prompt, ?string $default = null): string

docs/en/contents.md

@@ -64,7 +64,7 @@
 - [Authorization](https://book.cakephp.org/authorization/3/)
 - [Bake](https://book.cakephp.org/bake/3/)
 - [Debug Kit](https://book.cakephp.org/debugkit/5/)
-- [Migrations](https://book.cakephp.org/migrations/4/)
+- [Migrations](https://book.cakephp.org/migrations/)
 - [Elasticsearch](https://book.cakephp.org/elasticsearch/4/)
 - [Phinx](https://book.cakephp.org/phinx/0/en/)
 - [Chronos](https://book.cakephp.org/chronos/3/)

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: