Update serializer.rst

[ThomasLandauer]

The page is still a mess, but a tried to (at least) improve it a little.

The main problem (to me) is that there a two pages for (basically) the same:

• https://symfony.com/doc/4.0/serializer.html
• https://symfony.com/doc/4.0/components/serializer.html

...which sometimes contradict each other, sometimes repeat each other and sometimes enhance each other. What's the advantage of having two pages at all? Why not merge them?

Some additional ideas for future improvements:

• Show a copy-pastable example of serializing an entity from the database, since this is (probably) the most common use-case.
• Show ->select('a.name, a.price, a.desc') together with ->getArrayResult() as an alternative to the @Groups annotation
• When is dependency injection possible (or superior) over new Serializer(...)?
• Error message "A circular reference has been detected (configured limit: 1)"

I edited the 4.0 version, since the page differs notably between versions, and I wasn't sure which one to take.

[javiereguiluz]

/components/serializer.rst is for people using the Serializer component out of Symfony apps and /serializer.rst is when using it inside a Symfony app.

Sadly sometimes this results in some duplications. Overall, these would be the differences:

• Components article explain the low level installation, the autoloading, etc. Main article assumes the reader is using Flex: composer require ... and done.
• Features of the component should be explained in the component article and not in the main article...
• ... except when using those features is different (i.e. simpler and better) when using the component inside a Symfony app. Then it's when there are some duplicated explanations.
• The component page can't explain how to use Serializer with other components. Each component article is stand-alone, so cross-features are explained in the main article.

@ThomasLandauer is it more clear now?

[ThomasLandauer]

Yeah, somewhat - thanks! :-)

Can I ask you some questions for me (or somebody else) to be able to make more improvements?

1. So the list of available normalizers and encoders (i.e. this chapter https://symfony.com/doc/4.0/serializer.html#adding-normalizers-and-encoders ) needs to move to /components/serializer.rst? The only relevant aspect to /serializer.rst is the services.yaml part?

2. Is dependency injection really simpler/better than $serializer = new Serializer($normalizers, $encoders);? I mean, you probably need to do some configuration anyway (i.e. DateTime export settings)...
   If YES: Include more examples on /serializer.rst on how to do the configuration in services.yaml.
   If NO: Say that instantiation is the preferred method, and only show dependency injection as a handy alternative for some (which?) cases.

3. So everything Doctrine- or (entity-) related needs to be on /serializer.rst? Do you agree that serializing an entity from the database is the most probable use-case?

[javiereguiluz]

@ThomasLandauer those are great questions ... but the Serializer component is not my strong suit so I can't answer to them.

Let's ask to our doc maintainers @wouterj and @xabbuh ... and also to Serializer and Symfony experts @dunglas and @Simperfit. Thanks!

[dunglas]

For the record I'm 👍 to merge both pages, and add examples explaining how to use features using the full stack framework, then example on how to initialize the required class in component mode.

If we don't merge it:

1. The component doc definitely more relevant
2. I don't understand what you mean, can you detail?
3. To me it's an important use case, but not the most relevant use case, it's one use case among a lot of others (consuming an external web API, serializing classes coming from Elastic/Mongo/Firebase/whatever

[dunglas]

If we don't merge both pages, it should be in the component page, not here.

[dunglas]

👎, when using the full stack framework, the service registered by FrameworkBundle should alway be used. Here you don't benefit from the cache layer, groups, max depth...
Initializing the component manually belongs to the component docs.

[dunglas]

Not true, they are automatically registered (to usr the YAML encoder, the Yaml component must be installed): https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Resources/config/serializer.xml#L112-L118

[dunglas]

I would not mention this normalizer here. We'll maybe deprecate it at some point.

[dunglas]

👍 to drop this block, but I'll not mention it in this documentation (why not in the component one, but it's confusion for frameworkbundle users)

[ThomasLandauer]

For the record I'm +1 to merge both pages

So should we wait for additional opinions or go ahead and start merging?

2. Is basically answered by "when using the full stack framework, the service registered by FrameworkBundle should alway be used."
   But please tell me how to do configuration (e.g. the equivalent to new DateTimeNormalizer('Y-m-d')) when using the service.

I'm ignoring your other comments for now - till the big question (merge?) is answered :-)

[dunglas]

But please tell me how to do configuration (e.g. the equivalent to new DateTimeNormalizer('Y-m-d')) when using the service.

To configure it globally, you have to override the service definition:

# config/services.yaml serializer.normalizer.datetime: class: Symfony\Component\Serializer\Normalizer\DateTimeNormalizer arguments: ['Y-m-d'] tags: [{name: serializer.normalizer, priority: -910}]

Alternatively, you can change the format using the datetime_format context option (a datetime_timezone context option is also available): https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Serializer/Normalizer/DateTimeNormalizer.php#L54

[javiereguiluz]

For the record I'm +1 to merge both pages

So should we wait for additional opinions or go ahead and start merging?

If you are thinking about deleting one of the two pages, that's not possible. We must maintain the component page for sure ... and the main article too (if it's still relevant). For some components we don't have a main page: e.g. DomCrawler ... we only mention it briefly in the main testing.rst page ... but all its docs are in components/* If you think that there's nothing to say about using Serializer into Symfony, we can then remove the main page. But I highly doubt that. Thanks!

[weaverryan]

Hi guys!

Thanks for the PR - let's fix this! First, I think we do need both articles. Typically, we put most of the documentation into the framework document and then only put the details about how to instantiate & setup the objects in the component documentation. To say it differently, the framework is the first class citizen. If you're using a component, we need to give you the details on how to set things up, but for usage, you will need to go look at the framework docs (which, besides how you get/instantiate the object, the usage is the same).

Translation is a pretty good example:

• Framework: https://symfony.com/doc/current/translation.html
• Component: https://symfony.com/doc/current/components/translation.html

For the serializer, I think we should do this in 3 steps (could be 3 PRs or 1 PR):

1. Rewrite the framework docs
2. Move some more advanced topics from the component into sub-articles below the framework docs
3. Refactor (remove most of) the component docs

For step (2) [rewrite the framework documentation], we should probably steal a lot from the component documentation, which is much more complete (it has a diagram, shows an example class, shows serializing/deserializing objects). For the first "draft", we should probably just include the following topics:

• Installation
• Fetching the service
• showing a class
• Showing how to serialize that class
• Showing how to deserialize
• Showing serialization groups

Does anyone disagree or have any thoughts? @ThomasLandauer As we're all quite busy, we would LOVE to have your help with this. It's very important - we just need more good people to help!

[javiereguiluz]

@ThomasLandauer I'd love to see this pull request move forward. However, in my experience, pull requests that try to do too many things always fail: too many merge conflicts, endless discussions, etc.

So, if you have some time for this, could you send a small pull request to fix the most urgent problems of this article ... and later, if needed, submit other PRs to fix further things? Thanks!

[javiereguiluz]

It's sad but I'm going to close this PR without merging because it has too many conflicts, unrelated changes, targerts an unmaintained branch, etc.

@ThomasLandauer I'm really sorry. I hope you can recover some of your commits and apply them to 4.1 branch so we can review and merge. If you do so, please try to do not many changes in order to ease reviewing it. Thanks a lot!