Add DTO projection support via projectAs() query method by dereuromark · Pull Request #19135 · cakephp/cakephp

dereuromark · 2025-12-17T04:33:01Z

Summary

Add projectAs() method on SelectQuery to project results directly into readonly DTOs instead of Entity objects
Support two DTO creation styles: DtoMapper (reflection-based) and createFromArray() factory method
Add #[CollectionOf] attribute for specifying collection element types
Handle nested association hydration into DTOs

Usage

// Simple DTO projection
$articles = $articlesTable->find()
    ->projectAs(ArticleDto::class)
    ->toArray();

// With associations
$articles = $articlesTable->find()
    ->contain(['Authors', 'Comments'])
    ->projectAs(ArticleDto::class)
    ->toArray();

DTO classes can use either constructor parameters (mapped via reflection):

readonly class ArticleDto {
    public function __construct(
        public int $id,
        public string $title,
        public ?AuthorDto $author = null,
        #[CollectionOf(CommentDto::class)]
        public array $comments = [],
    ) {}
}

Or a createFromArray() factory method for full control over mapping:

readonly class ArticleDto {
    public function __construct(
        public int $id,
        public string $title,
        public ?AuthorDto $author = null,
    ) {}
    
    public static function createFromArray(array $data, bool $ignoreMissing = false): self {
        return new self(
            id: $data['id'],
            title: $data['title'],
            author: isset($data['author']) 
                ? AuthorDto::createFromArray($data['author'], $ignoreMissing)
                : null,
        );
    }
}

Performance

DTOs use approximately 3x less memory than Entity objects while providing similar hydration speed. The createFromArray() method is ~2.5x faster than Entity hydration.

Refs #19131

Adds ability to project ORM query results directly into readonly DTOs instead of Entity objects. This provides a more memory-efficient and immutable way to fetch read-only data. New features: - projectAs() method on SelectQuery to specify a DTO class - DtoMapper using PHP 8 reflection with named constructor arguments - CollectionOf attribute for specifying array collection element types - Support for createFromArray() factory method (cakephp-dto style) - Nested association hydration into DTOs

markstory · 2025-12-17T05:08:20Z

+ *     public function __construct(
+ *         public int $id,
+ *         public string $title,
+ *         #[CollectionOf(CommentDto::class)]


This will be a good test to find out how the community likes APIs using attributes.

ADmad · 2025-12-17T11:54:47Z

How will fields like _joinData which are auto added to entities for BTM association be handled when using a DTO? Will they be dropped/ignored?

dereuromark · 2025-12-17T11:58:01Z

They will be mapped if present in the dto specs as property. I will check if there is a test.

ADmad · 2025-12-17T11:58:49Z

readonly class ArticleDto {
    public function __construct(
        public int $id,
        public string $title,
        public ?AuthorDto $author = null,
        #[CollectionOf(CommentDto::class)]
        public array $comments = [],
    ) {}
}

This looks similar to how an entity would look for the entity implementation I have made https://github.com/ADmad/cakephp-entity/blob/master/tests/test_app/TestApp/Model/Entity/Article.php

<?php
declare(strict_types=1);

namespace TestApp\Model\Entity;

use ADmad\Entity\Datasource\Entity;
use BackedEnum;
use DateTimeInterface;

class Article extends Entity
{
    protected ?int $id;
    protected ?int $author_id;
    protected $user_id;
    protected string $title;
    protected ?string $body;
    protected string|BackedEnum $published;
    protected ?DateTimeInterface $created;
    protected ?DateTimeInterface $modified;
    protected ?DateTimeInterface $updated;
    protected ?DateTimeInterface $date_specialed;
    protected array $tags;
    protected ?Author $author;
    protected array $comments;
    protected array $unaproved_comments;
    protected $article;
    protected $not_in_schema;

    protected $comments_notype;
    protected $user;

    public function isRequired(): bool
    {
        return true;
    }
}

rochamarcelo · 2025-12-17T12:04:29Z

+        public string $class,
+    ) {
+    }
+}


Could we have a simple attribute with all possible configs? Here is an example with name and collectionOf, both are optional

```php readonly class ArticleDto { public function __construct( public int $id, #[FieldDto(name: "main_title")] public string $title, #[FieldDto(collectionOf: CommentDto::class)] public array $comments = [], ) {} } ```

Isnt that bit of scope creep? Renaming the fields is a bit of different concern
Usually thats handled in the DTOs using from/to kind of mapping configs.

Doing attribute aliasing/inflection is a good scenario for createFromArray() as well.

What do you propose here @markstory ?
Maybe you can clarify

Renaming the fields is a bit of different concern

Being able to rename fields would be quite handy for tasks like report generation. For e.g. being able to represent author.name as author_name in xls/csv rendering.

OK, what would be the naming/signature be then for this attribute?
If we brainstorm on full specs now first, I can finish this up in one batch.

And:
Should I implement this as a replacement for #[CollectionOf], or keep both (with #[CollectionOf] as shorthand)?

Maybe you can clarify

My thought here is that we build provide simple constructor support, and if userland code need attribute renames, inflections or anything along those lines they can implement createFromArray(). We can add more attributes and more 'configuration' to DTO mapping later when we better understand the gaps/limitations in our simple solution.

OK, so we address this later if needed.

DateTime and other objects type-hinted on constructor parameters were incorrectly being passed to map() as if they were arrays for nested DTO mapping. Added is_array() check to only map actual arrays. Added test cases for DateTime object handling.

Previously, DTO mapping happened in ResultSetFactory::groupResult() during hydration, BEFORE formatters ran. This caused issues with behaviors like TagBehavior that add formatters expecting arrays/entities. Now DTO projection: 1. Returns arrays from groupResult() when projectAs() is used 2. Applies DTO mapping as a FINAL formatter after all others 3. Allows behavior formatters to work with arrays/entities first This aligns with the user-space approach suggested in PR review: disableHydration()->formatResults() but built-in for convenience.

Use hydrateDto() (now public) instead of getDtoMapper()->map() directly so that DTOs with static createFromArray() factory methods (cakephp-dto style) continue to work.

dereuromark · 2025-12-17T16:28:14Z

@ADmad
The sandbox examples show it live if run locally:
dereuromark/cakephp-sandbox@b5ece85
ignored unless you set a field for it, then it will be included as array/DTO:

Option 1: ?array (simple)

  readonly class UserWithMatchingDto {
      public function __construct(
          public int $id,
          public string $username,
          public ?array $_matchingData = null,
      ) {}
  }

Option 2: ?MatchingDataDto (full type safety)

  readonly class MatchingDataDto {
      public function __construct(
          public ?SimpleRoleDto $Roles = null,  // Property name = association alias
      ) {}
  }

  readonly class UserWithMatchingDtoTyped {
      public function __construct(
          public int $id,
          public string $username,
          public ?MatchingDataDto $_matchingData = null,
      ) {}
  }

dereuromark · 2025-12-17T16:37:25Z

To support a wider range of DTO libs, we might want to create a DtoRegistry or some Configure approach on how to map them.
Or simply allow a factory to be passed:

  // For Valinor (external mapper)
  ->projectAs(UserDto::class, fn($data) => $valinorMapper->map(UserDto::class, $data))

Implementation:

  public function projectAs(string $dtoClass, ?callable $factory = null): static {
      $this->_dtoClass = $dtoClass;
      $this->_dtoFactory = $factory;
      return $this;
  }

markstory · 2025-12-18T04:08:37Z

->projectAs(UserDto::class, fn($data) => $valinorMapper->map(UserDto::class, $data))

Is this something that is needed now? I think we should see if we can get the design right and get some adoption before we need to make it pluggable.

dereuromark · 2025-12-18T11:18:37Z

Providing the factory possibility wouldn't hurt IMO, since it would not be used in default cases anyway.
Without it using custom DTO libraries or any mapping library would be not easy to achieve I assume.

rochamarcelo · 2025-12-18T16:56:42Z

Does this feature works with column type Enum?

//In table initialize
 $schema->setColumnType('status', EnumType::from(\App\Enum\Status::class));

//In DTO class
`public \App\Enum\Status $status`

dereuromark · 2025-12-18T16:58:39Z

I would think so. Enums are also just classes. The DTO just has to define them. See test cases in cake-dto.

//EDIT @rochamarcelo I added a real life test in sandbox for enums, works.

dereuromark · 2025-12-21T12:24:19Z

Are we then able to move forward?

markstory

Generally looks good to me. I think this feature will require documentation on what a DTO is, and give developers context on when/why they would use projectAs() instead of getting results as entities & arrays.

markstory · 2025-12-28T03:55:33Z

+        public ?DateTime $created = null,
+        public ?DateTime $modified = null,


Do we need special casing for application enums or other custom application type mappings?

As per my sandbox example code this all works as is.

Documents the new projectAs() method for projecting ORM results into DTOs instead of Entity objects, including the #[CollectionOf] attribute for nested associations. Refs cakephp/cakephp#19135

dereuromark added this to the 5.3.0 milestone Dec 17, 2025

Fix phpstan error with class-string type assertions

d26aa7d

markstory reviewed Dec 17, 2025

View reviewed changes

dereuromark marked this pull request as ready for review December 17, 2025 11:32

dereuromark added the enhancement label Dec 17, 2025

rochamarcelo reviewed Dec 17, 2025

View reviewed changes

Comment thread src/ORM/DtoMapper.php

rochamarcelo reviewed Dec 17, 2025

View reviewed changes

Comment thread src/ORM/Attribute/CollectionOf.php

rochamarcelo reviewed Dec 17, 2025

View reviewed changes

dereuromark added 4 commits December 17, 2025 14:13

Move CollectionOf attribute to Cake\ORM\Attribute namespace

fec509e

Restore createFromArray support in DTO projection

d71f584

Use hydrateDto() (now public) instead of getDtoMapper()->map() directly so that DTOs with static createFromArray() factory methods (cakephp-dto style) continue to work.

dereuromark requested review from ADmad and markstory December 21, 2025 12:24

markstory reviewed Dec 28, 2025

View reviewed changes

dereuromark mentioned this pull request Dec 30, 2025

Add docs for SelectQuery::projectAs() DTO projection cakephp/docs#8148

Merged

LordSimal approved these changes Dec 30, 2025

View reviewed changes

markstory merged commit 24448d7 into 5.next Dec 31, 2025
15 checks passed

markstory deleted the 5.next-dto-projection branch December 31, 2025 04:07

jamisonbryant mentioned this pull request Jan 15, 2026

Entity Virtual Properties as Property Hooks PHP 8.4 #18201

Closed

ADmad mentioned this pull request Jan 17, 2026

RFC: ORM Enhancements - Identity Map & DTO Projection #19131

Closed

ADmad mentioned this pull request Apr 4, 2026

RFC – 6.0 – Concrete Entity Properties with Property Hook Support #19380

Open

dereuromark mentioned this pull request May 30, 2026

RFC: Make find() always return entities — explicit type-tracked reshaping via map() #19482

Open

		public ?DateTime $created = null,
		public ?DateTime $modified = null,

Conversation

dereuromark commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Usage

Performance

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ADmad commented Dec 17, 2025

Uh oh!

dereuromark commented Dec 17, 2025

Uh oh!

ADmad commented Dec 17, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dereuromark Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dereuromark commented Dec 17, 2025

Uh oh!

dereuromark commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

markstory commented Dec 18, 2025

Uh oh!

dereuromark commented Dec 18, 2025

Uh oh!

rochamarcelo commented Dec 18, 2025

Uh oh!

dereuromark commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dereuromark commented Dec 21, 2025

Uh oh!

markstory left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

dereuromark commented Dec 17, 2025 •

edited

Loading

dereuromark Dec 18, 2025 •

edited

Loading

dereuromark commented Dec 17, 2025 •

edited

Loading

dereuromark commented Dec 18, 2025 •

edited

Loading