Hacktoberfest 2026 : les issues que les mainteneurs ont marquées pour octobre, ouvertes et accessibles aux débutants. Parcourir les issues Hacktoberfest

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

Ouverte
  • Quelque chose ne va pas ?
#8,765 1 commentaire 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
4/5
Temps estimé
3-5 jours
Accessibilité débutants
20/100
Type d'issue
Fonctionnalité
Clarté
Plutôt claire
Activité
Active
Stack technique
php
Domaine
api, performance

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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.

Langage dominant
PHP
Étoiles
2.6k
Forks
987
Merge moyen
1 j 22 h
PR mergées (30 j)
87

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de api-platform/core

Toutes les issues de api-platform/core

Issues similaires

Plus d'issues PHP

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.