From ced29fffc75c7d3ee1971e32174450cf8347f04d Mon Sep 17 00:00:00 2001
From: Mark Scherer <dereuromark@users.noreply.github.com>
Date: Thu, 5 Nov 2026 03:06:03 +0100
Subject: [PATCH] Document Table::list()

---
 docs/en/appendices/5-5-migration-guide.md     |  6 +++++
 docs/en/orm/retrieving-data-and-resultsets.md | 25 +++++++++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/docs/en/appendices/5-5-migration-guide.md b/docs/en/appendices/5-5-migration-guide.md
index 67a1eb601e..e8bb0207bb 100644
--- a/docs/en/appendices/5-5-migration-guide.md
+++ b/docs/en/appendices/5-5-migration-guide.md
@@ -59,6 +59,12 @@ bin/cake upgrade rector --rules cakephp55 <path/to/app/src>
   object provides a fluent interface for defining JSON path expressions.
 - ``FunctionsBuilder::jsonExists()`` was added.
 
+### ORM
+
+- `Table::list()` was added. It runs the `list` finder and returns the
+  key/value array directly. See
+  [Getting The List As An Array](../orm/retrieving-data-and-resultsets#getting-the-list-as-an-array).
+
 ### TestSuite
 
 - `Cake\TestSuite\Fixture\DeleteStrategy` was added. This fixture strategy
diff --git a/docs/en/orm/retrieving-data-and-resultsets.md b/docs/en/orm/retrieving-data-and-resultsets.md
index 17b82233d7..dbd573b8c3 100644
--- a/docs/en/orm/retrieving-data-and-resultsets.md
+++ b/docs/en/orm/retrieving-data-and-resultsets.md
@@ -334,6 +334,31 @@ The `keyField`, `valueField`, and `groupField` expression will operate on
 entity attribute paths not the database columns. This means that you can use
 virtual fields in the results of `find(list)`.
 
+### Getting The List As An Array
+
+`Table::list()` runs the `list` finder and returns the resulting array. It
+takes the same `keyField`, `valueField`, `groupField` and `valueSeparator`
+options as the finder:
+
+```php
+$data = $articles->list(valueField: 'label');
+
+// Build the query first to add conditions or stack other finders
+$data = $articles->list(
+    $articles->find()->where(['published' => true])->orderBy(['title' => 'ASC']),
+    keyField: 'slug',
+    valueField: 'label',
+);
+```
+
+Unlike `find('list')`, which is statically typed as a query of entities,
+`list()` is typed as returning an array, so static analysis tools see the real
+result.
+
+::: info Added in version 5.5.0
+`Table::list()` was added.
+:::
+
 ### Customize Key-Value Output
 
 Lastly it is possible to use closures to access entity accessor methods in your