How to make association between two DTO classes using stateOptions

[mleko64]

Supose I have two Entity classes:

#[ORM\Entity]
class BookEntity
{
    public function __construct(
        #[ORM\Id]
        #[ORM\Column]
        public int $id,
        #[ORM\Column]
        public string $title,
        #[ORM\ManyToOne(targetEntity: AutorEntity::class, inversedBy: 'books')]
        public Author $author,
    ) {}
}

#[ORM\Entity]
class AuthorEntity
{
    public function __construct(
        #[ORM\Id]
        #[ORM\Column]
        public int $id,
        #[ORM\Column]
        public string $name,
        #[ORM\OneToMany(targetEntity: BookEntity::class, mappedBy: 'author')]
        public Collection $books;
    ) {
        $this->books = new ArrayCollection();
    }
}

And also I have two DTO classes:

#[ApiResource(
    operations: [
        new Get(),
        new GetCollection(),
    ],
    stateOptions: new Options(entityClass: BookEntity::class)
)]
class BookApi
{
    public int $id;
    public string $title;
    public AuthorApi $author;
}

#[ApiResource(
    operations: [
        new Get(),
        new GetCollection(),
    ],
    stateOptions: new Options(entityClass: AuthorEntity::class)
)]
class AuthorApi
{
    public int $id;
    public string $name;

    /**
     * array<BookApi>
     */
    public array $books;
}

1. How to handle this situation to map $author as AuthorApi object (in BookApi) and $books as collection (array) of BookApi objects (in AuthorApi)?
2. How to tell API Platform to expose $books field as collection of BookApi, but should be fetch BookEntity objects behind the scene?

I don't want mix up entities with DTO classes, for example:

class BookApi
{
    public int $id;
    public string $title;
    public AuthorEntity $author; // I don't want mix-up Entity with DTO
}

I tried to use "symfony/object-mapper" but no chance so far.
Thanks for Your help.

[solariox]

I am struggling with the exact same problem for weeks now.

I've summarized some of my research here, if you want to take a look:
https://gist.github.com/solariox/2e6726afe36ac62ad9bf005a69fb2cf0

For inputs, we don't have a satisfying result right now.
For simple case, ObjectMapper is working fine. But as soon as we want to handle sub-resource, like giving IRI in a POST, we end up to use a custom processor, because we cannot succeed other way.

For Outputs, we've end up to use a mix of serializer groups, with custom source/target attributes if needed.

[soyuka]

It's really interesting, could we add this example on https://github.com/mtarld/sfcon-apip/ ? We're trying to get a nice reference for this out there then we'll fix our docs.

[mleko64]

@solariox
The first option would be great if multiple uses of the #[Map] attribute were handled automatically.
I mean for example:

// Book entity
class Book  
{
    #[ORM\ManyToOne(inversedBy: 'books')]  
    private ?Author $author = null;
}

// Author Entity
// Multiple Map attribute not works automatically :(
#[Map(target: OutputAuthorDTO::class)]
#[Map(target: AnotherOutputAuthorDTO::class)]
class Author {
    #[ORM\Column(length: 255)]  
    private ?string $name = null;
    
    #[ORM\OneToMany(targetEntity: Book::class, mappedBy: 'author')]  
    private Collection $books;
}

// DTO 1
class OutputAuthorDTO
{
    public string $name;
}

// DTO 2
class AnotherOutputAuthorDTO
{
    public string $books;
}

// Book resource
#[ApiResource(    
    stateOptions: new Options(entityClass: Book::class)  
)]
#[GetCollection(  
    uriTemplate: '/books',  
    provider: BookResourceProvider::class,  
)]
#[Map(source: Book::class)]
class BookResource
{
    public OutputAuthorDTO $author;
    #[Map(source: 'author')]
    public AnotherOutputAuthorDTO $anotherAuthor;
}

With this config, I gets error:

Expected argument of type "App\ApiResource\OutputAuthorDTO", "App\ApiResource\AnotherOutputAuthorDTO" given at property path "author".

If I swap these 2 #[Map] attributes, then I gets error:

Expected argument of type "App\ApiResource\AnotherOutputAuthorDTO", "App\ApiResource\OutputAuthorDTO" given at property path "anotherAuthor".

So, I guess the last #[Map] attribute is taken into account.

[soyuka]

I don't understand could you explain what you want to achieve?

[mleko64]

I created this discussion because I didn't know how to bind 2 DTO classes as associations using stateOptions and the symfony/object-mapper library. @solariox did a good research and presented several ways how to accomplish this.
The first option presented by @solariox is nice in my opinion because it requires minimal configuration, but it has the drawback of not being able to automatically map the same entity multiple times to different DTO classes. It forces us to create a custom StateProvider and perform the mapping manually (option number 3). I just pointed out that if there was some way to automatically resolve multiple entity mappings to different DTO classes, that would be super great. That's all.

[soyuka]

I read @solariox gist, the thing I'm missing is the big picture. If you need
several embedded object representations, then it's your main object that has 2
representations? For example:

 // You'd have different BookResource classes for different contexts?
 #[ApiResource(stateOptions: new Options(entityClass: Book::class))]
 class BookResourceWithFullAuthor
 {
     public FullAuthorDTO $author;
 }

 #[ApiResource(stateOptions: new Options(entityClass: Book::class))]
 class BookResourceWithMinimalAuthor
 {
     public MinimalAuthorDTO $author;
 }

Or are you using different operations on the same resource? Because if I
understand correctly, Option 1 in the gist doesn't work when you need multiple
representations of the same relation (Author → OutputAuthorDTO vs
AnotherAuthorOutputDTO) depending on which parent resource is requesting it.

Maybe the solution is to have different ApiResource classes for different use
cases (list vs detail, different contexts) rather than trying to make one
ApiResource flexible enough to handle multiple child representations?

What's your use case specifically - do you need the same Book resource to
sometimes show author with full details and sometimes with minimal details?

[Cafeine42]

I pushed a minimal reproducer for the Api/Resource association issue with ObjectMapper.
dff9c93

#[ApiProperty(readableLink: false, writableLink: false)] is ignored in my reproducer, and i fail to make a POST with en nested IRI.

[Cafeine42]

Idea : Decorate ObjectMapperMetadataFactoryInterface to inject a specific mapping when the target is a Doctrine entity. The mapping would include a class transformer that retrieves the managed Doctrine entity using the correct primary keys and the provided state options.
If the class transform work.

[Cafeine42]

After testing many things with the ObjectMapper component in my project and going through a lot of frustration, I ended up reimplementing the ObjectMapper component to support factories, injectable services for global transformations, predefined mappings based on a given source and target, and other features. The interface contract is not complicated (map source & target).

That part is done.

I started using it with ApiPlatform integration. For read operations, there is no issue; I did not have any with the original component either (except for nested class transforms, but that has been fixed since this morning).

However, for write operations (POST/PATCH/PUT), the first problems I encounter are the following:

In ObjectMapperProcessor, on a POST request, $request?->attributes->get('mapped_data') is empty, which is logical for a creation. As a result, the expected class is not even sent to the mapper, which then picks randomly among the possible mappings (and in my implementation, no mapping is allowed without an identified target, so this results in an error).

So I added the StateOptionsTrait trait and modified the call to $this->decorated->process as follows:

// maps the Resource to an Entity
if ($request?->attributes->get('mapped_data')) {
    $mappedData = $this->objectMapper->map($data, $request?->attributes->get('mapped_data'));
} else {
    $mappedData = $this->objectMapper->map($data, $this->getStateOptionsClass($operation));
    $request?->attributes->set('mapped_data', $mappedData);
}

$persisted = $this->decorated->process(
    $mappedData,
    $operation,
    $uriVariables,
    $context,
);

I also noticed that the return:

return $this->objectMapper->map(
    // persist the entity
    $persisted,
    $operation->getClass()
);

does not take a potential output DTO into account. It will be a problem on somes of my endpoints.

For “de-mapping” when you pass a DTO with properties that are ApiResources, I wrote a ClassTransform that directly fetches the Doctrine entity. I think I can improve it by leveraging the ApiProperty attributes to decide whether it should just take the entity (IRI provided) or also map what it contains (writableLink).

/**
 * @implements GlobalTransformInterface<object, object>
 */
final readonly class DoctrineClassTransformer implements GlobalTransformInterface
{
    public function __construct(
        private ManagerRegistry $managerRegistry,
    ) {
    }

    public function __invoke($source, $target): object
    {
        $toClass = $target::class;

        // TODO Improve, assert it's an ApiRessource, find id by #[ApiProperty(identifier: true)] or api metadata
        /** @phpstan-ignore-next-line property.notFound */
        $id = $source->id;

        $manager = $this->managerRegistry->getManagerForClass($toClass);

        if (null === $manager) {
            throw new \RuntimeException(\sprintf('No manager found for class %s', $toClass));
        }

        $repository = $manager->getRepository($toClass);

        $entity = $repository->find($id);

        if (null === $entity) {
            throw new ItemNotFoundException(\sprintf('Entity %s with id %s not found', $toClass, $id));
        }

        return $entity;
    }
}

I’m going to look into making this ClassTransform automatically applied when the target is a Doctrine entity, so I don’t have to hardcode it into every Map attribute. Probably a decorator around the mapping builder.

Then I have an issue with my security layer. I need access to Doctrine entity properties to determine whether the user can perform certain actions or not. From what I understand at this stage, ObjectMapperProcessor runs after post_denormalize and post_validate.

So I started looking into how to work around this. It would require either a security_post_mapper hook or a reordering so that the mapper runs after denormalization but before the security call in security_post_denormalize.