diff --git a/docs/en/appendices/5-5-migration-guide.md b/docs/en/appendices/5-5-migration-guide.md index 67a1eb601e..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 @@ -59,6 +65,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 + [Projecting Results Into DTOs](../orm/query-builder#dto-projection). + ### 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..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,13 +1037,23 @@ 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. +::: + +::: 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. :::