Jump to:

Problem/Motivation

We want to be able to easily serialize entities in different formats (JSON-LD, XML). We also want to be able to keep route/controller logic separate from the serialization logic. And serialization handling should be modular so new serializations can be added without any hacking of core files.

Proposed resolution

Symfony has a Serializer component. A Serializer has two parts, the Normalizer, which transforms a custom data structure to simple objects and arrays, and an Encoder, which takes the result of normalization and serializes it out in the chosen format.

The Normalizer and Encoder can specify rules under which they should work. For example, a Normalizer can say "only use me if the object is an Entity and the requested format is jsonld". This means that you can simply pass the object and format into the Serializer, and it will choose the correct one to use. This should enable format agnostic routes and controllers, maintaining the separation between the REST module and the serialization that we want to see.

There are also Denormalizers and Decoders, which reverse the serialization process and would be used to handle POST and PUT.

This patch used to apply for me, but when I did a fetch this morning, the composer.json and autoloader changes no longer applied. I'm going to retest this to see if it really does not apply anymore, or whether it's some glitch.

According to the original RFC, the Serializer component is in the 'least likely to stay backwards compatible' group for the Symfony 2.x cycle. How we handle upgrading Symfony version past 2.3 is still up in the air, but I'd like us to if at all possible.

This would be the first component from that (presumably less mature compared to the DIC, HTTPKernel and other critical components) group we committed to core. It'd be good to get an idea of how deep our API usage of this is likely to be.

In core, we would use Serializer::serialize and Serializer:deserialize in the entity CRUD routes defined by the REST module. Additionally, we would implement the Normalizer, Encoder, Denormalizer, and Decoder interfaces in JSON-LD module.

In contrib, any serialization module would implement the same interfaces as JSON-LD module.

I believe that usage would be confined enough in core that it could be resolved if a BC issue came about. I don't know how many serialization modules we'll have in contrib. Worst comes to worst, could we just update core's version of Symfony, but switch the Serializer to a fork until D9?

3 years is considerably shorter than the expected lifetime of Drupal 8, I'd expect at the very minimum we'd want to shift to the second LTS release even if we find we're not able to follow individual point releases.

#14 sounds reasonable to me. I don't see particular reason we couldn't hold back one component (or fork it) if we find there's an unresolvable problem updating it compared to others.

Just had a conversation with one of the co-authors of Serializer, he said the only 'big' change currently under discussion is to add $options to the Serializer parameters, https://github.com/symfony/symfony/pull/4938. This change doesn't really introduce anything backwards incompatible and would not affect us negatively.

Patch in #10 looks good, so RTBC. @catch: what else is needed to make a decision on the API stability concern: should this be assigned to Dries, or are you wanting more community discussion first?

Committing this patch, or deciding not to, is a requirement for web services, so I think major task is the correct classification, unless there's been a change to our classification system I'm not aware of, in which case, please correct me.

Just to confirm I'm fine with the approach in #14 too and committing on that basis. Dries normally does the commits for new libraries, so assigning to him.

I'm going to tag this with 'revisit before release' so that some time after 2.3 comes out we remember to have a look at upcoming PRs against the component. We'll be using it by then so should be in a good position to see if there's anything which could cause problems at that point.

I don't think that will be a problem for us. As far as I can see, there are very few times when we would want to compute XML element names directly from field names. I expect that there would be a mapping set up between the fields that the user defines and the elements that would be defined in the corresponding XML schema. In that case, a custom normalizer would get the element name that is mapped to the field name and use that.