Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#8,765 1 comentario 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
20/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
php
Área
api, performance

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
PHP
Estrellas
2.6k
Forks
987
Merge medio
1 d 22 h
PR fusionados (30 d)
87

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de api-platform/core

Todos los issues de api-platform/core

Issues similares

Más issues de PHP

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.