symfony
Combine component and framework docs for Serializer
A very early PR, to avoid someone else working on this as well (especially @fabpot who is on fire with this type of PRs lately).
The serializer docs are the most unfortunate component - framework documentation situations I think, with most of the docs in the component docs instead of framework one. This PR is focused on combining all the information in the framework guide as a start.
closes #17814
Wouter, thank you so much for this 🙇 This has been easily the worst part of the Symfony Docs for a long time. Let's make it as good as the other parts of the docs!
@wouterj is this task something that you still want to complete?
If yes, take as long as you need 🙏
If not, let's close this as let's think of other ways to improve existing Serializer docs.
Thanks!
Small update: Lots of delays, but with fresh energy after my holiday, I'm very very close to finishing this rewrite locally (and we can improve with follow up PRs later).
So here we are... It is not perfect, but I believe it's complete enough to be merged. :rocket: We can iterate upon it after it's fully merged. Thank you very much for the patience this far! :pray:
The biggest thing missing at the moment imho is explaining how the serializer reads properties from the class, and how it determines the properties type. It was and is very focused on reading the type that is passed through the (de)serialize method, not so much on reading the property type/PHPdoc/getter return type/etc. Also, the "Advanced Serialization" and "Advanced Deserialization" are a bit of a random collection of features. I've tried to order them by most-common to least-common. We might come up with a better way to organize the article in the future. There is a weird coupling of very low-level details and high level features (like what normalizer you must enable and configure in the context to get a specific feature), which made this an interesting challenge to organize in a beginner-friendly way.
I've not yet done a start to finish read of the new article (only scanning through it). It would be good if we good have a couple people reading it, and leaving feedback whenever they see something that requires attention :eyes: .
Whenever the reviews are finished, I'll find some time to merge this PR and deal with the many merge conflicts when up-merging it to 7.2.
I feel bad for pinging a PR that I've stalled for a year, but are you OK with me merging this one in the current state, @symfony/docs ? :)
@wouterj yes, please ... ship it whenever you can find some time for this. Thanks!
The sharp eye of @xabbuh revealed that this PR was a combination of 5.4 and 6.4 features. I've decided to completely rebase this PR to 6.4, given 5.4 is EOL this month and searching which 6.4 features unintentionally made it into this PR would be a huge task. Added a couple new sections about 6.4 features that were documented already.
When build is green, I'll merge this into 6.4 & 7.x.