From 6a30eb973e1a1bf1b9a17af6e54d440b44fc46e1 Mon Sep 17 00:00:00 2001 From: Mark Scherer Date: Thu, 5 Nov 2026 03:06:05 +0100 Subject: [PATCH 1/2] Document Table::projectAs() and Table::projectOne() --- docs/en/appendices/5-5-migration-guide.md | 6 +++++ docs/en/orm/query-builder.md | 31 +++++++++++++++++++++++ 2 files changed, 37 insertions(+) diff --git a/docs/en/appendices/5-5-migration-guide.md b/docs/en/appendices/5-5-migration-guide.md index 67a1eb601e..8174200e21 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 object provides a fluent interface for defining JSON path expressions. - ``FunctionsBuilder::jsonExists()`` was added. +### ORM + +- `Table::projectAs()` and `Table::projectOne()` were added. They project + query results into DTOs and are typed as the DTO class. See + [Typed DTO Results From The Table](../orm/query-builder#typed-dto-results-from-the-table). + ### TestSuite - `Cake\TestSuite\Fixture\DeleteStrategy` was added. This fixture strategy diff --git a/docs/en/orm/query-builder.md b/docs/en/orm/query-builder.md index 325f20c2b0..61a8ff0449 100644 --- a/docs/en/orm/query-builder.md +++ b/docs/en/orm/query-builder.md @@ -1021,6 +1021,37 @@ schema, making it easier to evolve your API without changing your data model. The `projectAs()` method and `#[CollectionOf]` attribute were added. ::: +#### Typed DTO Results From The Table + +`SelectQuery::projectAs()` changes what the query returns at runtime, but the +query is still typed as a collection of entities, so static analysis sees an +entity where the code gets a DTO. `Table::projectAs()` and +`Table::projectOne()` run the projection and are typed as the DTO class: + +```php +// list +$articles = $articlesTable->projectAs(ArticleDto::class); + +// ArticleDto|null +$article = $articlesTable->projectOne( + ArticleDto::class, + $articlesTable->find()->where(['Articles.id' => $id]), +); +``` + +Both methods take an optional query as the second argument, so you can add +conditions, contain associations or stack finders before projecting. Without a +query they start from `find()`. `projectOne()` limits an unexecuted query to +one row, like `first()`. + +If a row does not end up as an instance of the requested class, for example +because a `createFromArray()` factory returns another type, both methods throw +a `CakeException`. + +::: info Added in version 5.5.0 +`Table::projectAs()` and `Table::projectOne()` were added. +::: + ### Adding Calculated Fields From 8fd3cf04968f71283d6a62442035686d9dc25b77 Mon Sep 17 00:00:00 2001 From: Mark Scherer Date: Sat, 14 Nov 2026 17:06:17 +0100 Subject: [PATCH 2/2] Lead DTO projection docs with the Table methods, deprecate SelectQuery::projectAs() --- docs/en/appendices/5-5-migration-guide.md | 8 +- docs/en/orm/query-builder.md | 98 ++++++++++++----------- 2 files changed, 58 insertions(+), 48 deletions(-) diff --git a/docs/en/appendices/5-5-migration-guide.md b/docs/en/appendices/5-5-migration-guide.md index 8174200e21..fcb3e05a6d 100644 --- a/docs/en/appendices/5-5-migration-guide.md +++ b/docs/en/appendices/5-5-migration-guide.md @@ -47,6 +47,12 @@ bin/cake upgrade rector --rules cakephp55 - `Cake\Database\Driver\Mysql::isMariaDb()` is deprecated. You should upgrade to the dedicated MariaDb driver instead. +### ORM + +- `SelectQuery::projectAs()`, `SelectQuery::getDtoClass()` and + `SelectQuery::isDtoProjectionEnabled()` are deprecated. Use + `Table::projectAs()` or `Table::projectOne()` instead. + ## New Features ### Database @@ -63,7 +69,7 @@ bin/cake upgrade rector --rules cakephp55 - `Table::projectAs()` and `Table::projectOne()` were added. They project query results into DTOs and are typed as the DTO class. See - [Typed DTO Results From The Table](../orm/query-builder#typed-dto-results-from-the-table). + [Projecting Results Into DTOs](../orm/query-builder#dto-projection). ### TestSuite diff --git a/docs/en/orm/query-builder.md b/docs/en/orm/query-builder.md index 61a8ff0449..c682799264 100644 --- a/docs/en/orm/query-builder.md +++ b/docs/en/orm/query-builder.md @@ -854,8 +854,8 @@ advantages: - **Read-only data** - Using `readonly` classes ensures data integrity and makes your intent clear. -The `projectAs()` method allows you to specify a DTO class that results will -be hydrated into: +`Table::projectAs()` takes a DTO class and returns a result set of DTO +instances. `Table::projectOne()` returns a single DTO or `null`: ```php // Define a DTO class @@ -869,13 +869,38 @@ readonly class ArticleDto } } -// Use projectAs() to hydrate results into DTOs -$articles = $articlesTable->find() - ->select(['id', 'title', 'body']) - ->projectAs(ArticleDto::class) - ->toArray(); +// ResultSetInterface +$articles = $articlesTable->projectAs(ArticleDto::class); + +// ArticleDto|null +$article = $articlesTable->projectOne( + ArticleDto::class, + $articlesTable->find()->where(['Articles.id' => $id]), +); ``` +Both methods take an optional query as the second argument, so you can select +fields, add conditions, contain associations or stack finders before +projecting. Without a query they start from `find()`. The query you pass is +not modified, and `projectOne()` limits it to one row, like `first()`. + +```php +$articles = $articlesTable->projectAs( + ArticleDto::class, + $articlesTable->find()->select(['id', 'title', 'body']), +); +``` + +The query fetches array rows and the table maps them, so both methods are +typed as the DTO class. If a row does not end up as an instance of the +requested class, for example because a `createFromArray()` factory returns +another type, both methods throw a `CakeException`. + +> [!NOTE] +> Collection methods that take a property path, such as `extract()` or +> `indexBy()`, read rows through array access. Pass a callback instead unless +> your DTO class implements `ArrayAccess`. + #### DTO Creation Methods CakePHP supports two approaches for creating DTOs: @@ -959,10 +984,10 @@ readonly class CommentDto } // Fetch articles with associations projected into DTOs -$articles = $articlesTable->find() - ->contain(['Authors', 'Comments']) - ->projectAs(ArticleDto::class) - ->toArray(); +$articles = $articlesTable->projectAs( + ArticleDto::class, + $articlesTable->find()->contain(['Authors', 'Comments']), +); ``` #### Using DTOs for API Responses @@ -999,10 +1024,10 @@ readonly class ArticleApiResponse } // In your controller -$articles = $this->Articles->find() - ->contain(['Authors']) - ->projectAs(ArticleApiResponse::class) - ->toArray(); +$articles = $this->Articles->projectAs( + ArticleApiResponse::class, + $this->Articles->find()->contain(['Authors']), +)->toList(); return $this->response->withType('application/json') ->withStringBody(json_encode(['articles' => $articles])); @@ -1012,46 +1037,25 @@ This approach keeps your API response format decoupled from your database schema, making it easier to evolve your API without changing your data model. > [!NOTE] -> DTO projection is applied as the final formatting step, after all other -> formatters and behaviors have processed the results. This ensures -> compatibility with existing behavior formatters while still providing the -> benefits of DTOs. +> DTO projection is applied as the final step, after all result formatters +> and behaviors have processed the rows, so existing behavior formatters keep +> working. ::: info Added in version 5.3.0 -The `projectAs()` method and `#[CollectionOf]` attribute were added. +The `#[CollectionOf]` attribute and `SelectQuery::projectAs()` were added. ::: -#### Typed DTO Results From The Table - -`SelectQuery::projectAs()` changes what the query returns at runtime, but the -query is still typed as a collection of entities, so static analysis sees an -entity where the code gets a DTO. `Table::projectAs()` and -`Table::projectOne()` run the projection and are typed as the DTO class: - -```php -// list -$articles = $articlesTable->projectAs(ArticleDto::class); - -// ArticleDto|null -$article = $articlesTable->projectOne( - ArticleDto::class, - $articlesTable->find()->where(['Articles.id' => $id]), -); -``` - -Both methods take an optional query as the second argument, so you can add -conditions, contain associations or stack finders before projecting. Without a -query they start from `find()`. `projectOne()` limits an unexecuted query to -one row, like `first()`. - -If a row does not end up as an instance of the requested class, for example -because a `createFromArray()` factory returns another type, both methods throw -a `CakeException`. - ::: info Added in version 5.5.0 `Table::projectAs()` and `Table::projectOne()` were added. ::: +::: info Deprecated in version 5.5.0 +`SelectQuery::projectAs()`, `SelectQuery::getDtoClass()` and +`SelectQuery::isDtoProjectionEnabled()` are deprecated. The query method +returns DTOs while the query stays typed as entities. Use +`Table::projectAs()` or `Table::projectOne()` instead. +::: + ### Adding Calculated Fields