5.5 - Document Table::list()

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

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