From ea8596db475d780627bc3824f90441dd9c0953e1 Mon Sep 17 00:00:00 2001
From: mscherer <dereuromark@web.de>
Date: Thu, 19 Mar 2026 14:51:32 +0100
Subject: [PATCH] Document Controller::defaultTable property

Add documentation about the $defaultTable property in controllers,
explaining how to customize it and that setting it to an empty string
is useful for controllers that don't use a table.

Refs cakephp/cakephp#19354
---
 docs/en/controllers.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/docs/en/controllers.md b/docs/en/controllers.md
index da901077f3..26c0cbfe50 100644
--- a/docs/en/controllers.md
+++ b/docs/en/controllers.md
@@ -559,6 +559,36 @@ $recentArticles = $this->fetchTable('Articles')->find('all',
 )->all();
 ```
 
+### The defaultTable Property
+
+By convention, controllers are associated with a primary model table. For
+example, `PostsController` will have `Posts` as its default table. You can
+customize this by setting the `$defaultTable` property:
+
+```php
+class PostsController extends AppController
+{
+    // Use Comments as the default table instead of Posts.
+    protected ?string $defaultTable = 'Comments';
+}
+```
+
+When `$defaultTable` is set, calling `fetchTable()` without arguments will
+return that table. If your controller doesn't use a table, you can set
+`$defaultTable` to an empty string:
+
+```php
+class DashboardController extends AppController
+{
+    // This controller doesn't use a table.
+    protected ?string $defaultTable = '';
+}
+```
+
+Setting `$defaultTable` to an empty string also prevents potential naming
+conflicts when loading components that share the same alias as the default
+table name.
+
 ### fetchModel()
 
 `method` Cake\\Controller\\Controller::**fetchModel**(?string $modelClass = null, ?string $modelType = null): object