Add a book entry for serialization

[dunglas]

The Serializer Component is being deeply reworked. It has gained some new features:

• Serialization groups: http://symfony.com/blog/new-in-symfony-2-7-serialization-groups
• Circular reference handling: [Serializer] Handle circular references symfony#12098
• Name Converters: [Serializer] Name converter support symfony#13120

I'm also working on making it a first class citizen of the framework (registered with the DIC and usable out of the box):

• [FrameworkBundle] Serializer groups support symfony#13107
• Serializer groups support symfony-standard#764

The next step will be to create a book entry (similar to the validation chapter) presenting basics and common uses of the Serializer with the full stack framework. We already started to discuss about that here: #4692 (comment)

What do you think about that? cc @wouterj @fabpot @Tobion @lsmith77 @Seldaek

[fabpot]

👍 for a book entry. Serialization is an important topic in modern apps.

[weaverryan]

@dunglas I just merged #4675, which is great, but the docs for the built-in serializer are really poor right now. As 2.7 is the first release where we (you) have finally made the serializer great, we should move quickly on the docs for it. Honestly, when I read the serializer docs we have so far, I'm confused about how to use it.

Here are some comments/questions I have - I am being a bit dumb, trying to get you my fresh impressions, which will probably be near what a new person will think:

1. I believe the ObjectNormalizer is not documented yet (other than being suddenly used in [Serializer] Doc for groups support #4675)

2. In the components docs, we go back and forth between the ObjectNormalizer and the GetSetMethodNormalizer. I don't really understand the difference. I believe ObjectNormalizer is the preferred, and if so, we should use it everywhere, and maybe just mention the GetSetMethodNormalizer.

3. The cookbook is terrible and uses the GetSetMethodNormalizer. Indeed, we need a proper chapter - I'm happy to help with this.

4. Is the setIgnoredAttributes() only for GetSetMethodNormalizer? Is there a way to ignore properties in the ObjectNormalizer, other than creating groups?

5. It looks difficult to control the name of just one serialized property, since you need to introduce a whole "name converter". If I had a few properties across several classes that were "odd" and didn't follow the pattern, should I create just one "name converter" for my class and include these exceptions in there? Or should I have a separate "name converter" for each class (and thus a normalizer for each class)?

Thanks!

[dunglas]

Hi,

The doc must be updated. It's on my todo list...

The two main thing to document IMO are:

• Object normalizer (it should be easy)
• How to use the serializer with the framework bundle as this is far more easy now than in 2.6

1. I believe the ObjectNormalizer is not documented yet (other than being suddenly used in [Serializer] Doc for groups support #4675)
   It's right.

2. In the components docs, we go back and forth between the ObjectNormalizer and the GetSetMethodNormalizer. I don't really understand the difference. I believe ObjectNormalizer is the preferred, and if so, we should use it everywhere, and maybe just mention the GetSetMethodNormalizer.

It's because I've not changed the existing doc. To summarize:

• ObjectNormalizer use PropertyAccess and is able to serialize using properties, getters, setters, adders... In fact every way to access a property allowed by PropertyAcces.
• GetSetMethodNormalizer only use getter and setters
• PropertyNormalizer only use properties

It sounds good to me to just mention GetSetMethodNormalizer et PropertyNormalizer.

3. The cookbook is terrible and uses the GetSetMethodNormalizer. Indeed, we need a proper chapter - I'm happy to help with this.

What about replacing the cookbook entry by a dedicated book entry (this issue)?

4. Is the setIgnoredAttributes() only for GetSetMethodNormalizer? Is there a way to ignore properties in the ObjectNormalizer, other than creating groups?

No, as for populating existing objects (another thing to document) and circular reference handling, I've moved this method it to AbstractNormalizer so it works with ObjectNormalizer, GetSetMethodNormalizer and PropertyNormalizer.

IMO, using this method is not a good idea and I'm to promote the use of groups instead.

5. It looks difficult to control the name of just one serialized property, since you need to introduce a whole "name converter". If I had a few properties across several classes that were "odd" and didn't follow the pattern, should I create just one "name converter" for my class and include these exceptions in there? Or should I have a separate "name converter" for each class (and thus a normalizer for each class)?

It's really up to you. I'll use only one "name converter" if there is only few case and split that converter if it start growing.

[weaverryan]

@dunglas agree on all points, and thanks for the clarifications! Any help you can offer to get the docs going is much appreciated. My worry would be that we all get busy and it doesn't get updated, which for most users would mean that the component is still unusable, and that would be a shame :). I will do my best, but I'm spread too thin to be dependable.

3. Agree on adding a book article. But my current philosophy is that the book should show the main use-cases. Anything that's more advanced or edge-case can be added to a cookbook. I hear often that people love the "How do I do X" articles in the cookbook, because it's so easy to find answers to questions when they're not hidden in the middle of a giant book article.

4. I agree on pushing groups instead of setIgnoredAttributes(), especially since that is set on the normalizer... which makes it seem to me that you'd need a normalizer for every object (is that correct?). Anyways, I think keeping the serializer metadata in one post (annotations, XML, whatever) is a big reason people like JMS, and using Groups only follows this.

5. I like the "name converter" idea, but I also do like the @SerializedName ability from JMS. So, maybe consider that a small vote for that feature from me ;).

Thanks @dunglas!

[GuilhemN]

I guess this is still actual, I tried to find a documentation describing how to create custom normalizers (to add it to the FOSRestBundle doc) but I didn't find.
If you want I can try to submit a pr but I didn't write many docs so I don't know how the result will be.

[wouterj]

@Ener-Getick such an article perfectly fits the components section, we don't need a book article for that. The good news is that you can start writing that article now :)

And don't worry about your doc-writing capabilities, we'll help you to create a nice article. If you're unsure about anything, don't hesitate to ask for help in a comment on GitHub or via the #symfony-docs channel on IRC.

[GuilhemN]

Thanks @wouterj, I won't have a lot of time during the 2 next weeks but I will probably create a [WIP] PR.
Maybe I'll see if I can simplify the serializer doc at the same time as I find it a bit complicated for a newcomer.

[GuilhemN]

I opened #6428

[javiereguiluz]

Closing because we no longer have a book. Moreover, the main serializer.rst article has been improved a lot lately and it will keep being improved.

[GuilhemN]

@javiereguiluz ok, thanks for the explanation !