Review messenger related documentation

[soyuka]

Related: https://github.com/api-platform/core/issues/3065 @asimonf do you see something we should clarify a bit more or that's missing here? Thanks!

[asimonf]

Related: api-platform/core#3065 @asimonf do you see something we should clarify a bit more or that's missing here? Thanks!

Thanks for asking.

If I'm not mistaken, given that the example is now a Book resource, it is entirely possible that someone uses that example as a base with a Doctrine entity that has relations with other entities. In such cases, if the native serializer is used for the message (Symfony\Component\Messenger\Transport\Serialization\PhpSerializer), those fields won't be properly merged to the object manager on the other side of the transport. Bare in mind that this serializer is the default since Symfony 4.3.

I think what's missing is either a mention that the above is expected behavior and the user should manually merge those fields back to the object manager in the message handler, or, make a mention that tells the user to change the native serializer to the default one at the cost of performance to avoid having to merge those entities and handle special cases. The latter would be possible using the following inside the messenger.yaml file.

framework:
    messenger:
        serializer:
            default_serializer: messenger.transport.symfony_serializer
            symfony_serializer:
                format: json
                context: { }

I don't know if the above will work just fine when using DTOs, though, so maybe just a mention, for now, that entities should be manually merged back?

Maybe a link to the documentation on Symfony's Messenger page would be appropriate. Also, maybe a mention that while functionally stable, this is still experimental and the API might change in future releases.

[soyuka]

Thank you very much for your input!

the user should manually merge those fields back to the object manager in the message handler, or, make a mention that tells the user to change the native serializer to the default one at the cost of performance to avoid having to merge those entities and handle special cases

Indeed, I'll definitely propose both solutions IMO both are valid. I'll also add a note that DTO will not work with API Platform's serializer because our serializer is working only with Resources tagged as ApiResource, they need to have an IRI (ie at least one GET operation in the Router).

@teohhanhui don't hesitate to comment if you think we should add something else!

[asimonf]

@teohhanhui @soyuka

I have a question regarding the latter part of the doc. What happens if, instead of implementing a POST, a PUT is implemented using a DTO. This would mean that the user is requesting an edit rather than creating a new resource. Is a data transformer called? If it is, when? Would there be a way to have access to the original object to perform the actual transformation? It isn't obvious to me, as an outsider, where would the Data Transformer enter into this, if it enters at all.

This is, of course, all assuming that the DTO is passing through the messenger component.

[soyuka]

Yes it will, and you'll have access to the Resource that needs to be updated see https://api-platform.com/docs/core/dto/#updating-a-resource-with-a-custom-input. The call to messenger will happen later when the resource should've been written (WriteListener, better docs about extension points soon https://github.com/api-platform/docs/pull/888).

Now the above is true with messenger=true and an input class.

If you set messenger=input the Input will not be transformed because it'll use this data transformer that just returns the input which will then be send to messenger.

Related issue that'll improve resources update with messenger: https://github.com/api-platform/core/issues/3082#issuecomment-535575673 (UpdateStamp implementation).

[Steveb-p]

If I can voice my opinion.

I've recently tried using messenger integration in my app and was surprised by the fact that enabling it causes my entity (which I used as input) to stop being saved to database. I'd love it if somewhere in documentation there would be a part warning that this works as a Data Persister and "replaces" the Doctrine one.

I now know that they are chained and the first supporting persister works, but it baffled me at the time. I couldn't figure out why enabling messenger integration for an entity caused my serializer to fail when trying to generate an IRI for the entity.