Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Eager loading for resources mapped to an entity through stateOptions (DTO output)

Aperta
  • Qualcosa non va?
#8,765 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
20/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
php
Ambito
api, performance

Direzione di ricerca

Start in EagerLoadingExtension::apply() and joinRelations(): apply() bails out without serialization groups/attributes, and joinRelations() builds metadata from $entityClass, so the DTO's #[ApiProperty(readableLink: true)] is ignored. Read #2002, #5062 and #8185 (fcfaf384) for the early-return and mapped-resource precedents. Done means a stateOptions: new Options(entityClass: ...) resource joins from its own readableLink/fetchEager properties, recursively through embedded resources, and the 30-item page no longer runs per-item queries; add eager-loading coverage.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Description

When a resource is a DTO backed by an entity through stateOptions: new Options(entityClass: ...), EagerLoadingExtension doesn't join any of the relations the DTO exposes. Each item then loads its relations lazily, which causes N+1 queries.

I understand that eager loading relies on serialization groups by design: apply() returns early without groups or attributes since #2002, to avoid recursive joins, and #5062 settled on documenting this rather than changing it. That makes sense for a resource that is the entity itself, where groups are the only way to tell which relations will be serialized.

A mapped resource is different: its class already describes the exact shape of the response. It usually needs no serialization groups, and adding some only to trigger eager loading duplicates that shape. Two things currently prevent the extension from using it:

  1. Without groups, apply() returns early, so nothing is joined, even with forceEager: true (the default).
  2. With groups or attributes, joinRelations() reads the property metadata of the entity ($propertyMetadataFactory->create($entityClass, $association)), not that of the resource. #[ApiProperty(readableLink: true)] on the resource's properties is therefore ignored. The entity's to-one relations get readableLink: null, so the extension stops after the first level.

The workarounds are:

  • to put API Platform metadata on the entity itself, which is what stateOptions is meant to avoid;
  • to declare a normalizationContext attributes tree that duplicates the resource class. The serializer also applies that tree, so it silently drops any field missing from it.

On our project (API Platform 5.0.5, Doctrine ORM 3), a paginated sub-collection of 30 items like the one below runs 167 queries where 10 would be enough: one query per item for the to-one relation, plus the to-many collections of each item.

This looks like the same kind of gap as #8185, fixed in fcfaf384 for nested property filters on mapped resources.

Example

#[ApiResource(
    operations: [
        new GetCollection(
            uriTemplate: '/libraries/{uuid}/books',
            uriVariables: ['uuid' => new Link(toProperty: 'library', fromClass: LibraryOutput::class)],
            provider: BookProvider::class, // Doctrine CollectionProvider + entity → DTO mapping
        ),
    ],
    stateOptions: new Options(entityClass: Book::class),
)]
final readonly class BookOutput
{
    public function __construct(
        public string $uuid,
        public string $title,
        #[ApiProperty(readableLink: true)]
        public AuthorOutput $author, // AuthorOutput embeds country (to-one) and awards (to-many)
        /** @var list<ReviewOutput> */
        #[ApiProperty(readableLink: true)]
        public array $reviews,
    ) {
    }
}

Current behavior: the page query selects only Book. Then author, its country and awards, and the reviews are loaded one book at a time.

Expected behavior: when the operation has stateOptions with an entityClass, the extension builds its join tree from the resource's property metadata instead of requiring groups. It follows the properties embedded with readableLink (or fetchEager), recursively through the embedded resources, and applies that tree to the entity's associations with the same names. The tree is bounded by what the resource embeds, which avoids the unbounded recursion that motivated #2002.

When the resource is mapped with the ObjectMapper (#[Map(source: ...)]), the same mapping could translate renamed properties into association names. We haven't checked whether ObjectMapperProvider has the same limitation, but it goes through the same Doctrine provider and extensions.

Would you accept such a change? If so, we can open a PR.

Lingua principale
PHP
Stelle
2.6k
Fork
987
Merge medio
1g 22h
PR unite (30g)
87

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di api-platform/core

Tutte le issue di api-platform/core

Issue simili

Altre issue su PHP

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.