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

carsonbot added the Status: Needs Review label

Jan 21, 2023

carsonbot added this to the5.4 milestone

Jan 21, 2023

wouterj marked this pull request as draft

January 21, 2023 15:44

Copy link

Member

javiereguiluz commentedJan 21, 2023

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!

Copy link

Member

fabpot commentedJan 21, 2023

I'm glad you're working on it :)

javiereguiluz mentioned this pull request

Jan 27, 2023

Contributions to Serializer docs are paused#17814

Closed

94noni reviewed

Jan 27, 2023

View reviewed changes

Copy link

Contributor

94noni left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

small review coming from#17814 :)

serializer.rst OutdatedShow resolvedHide resolved

serializer.rst

		// this creates a new Person instance based on the $jsonData
		// (which contains e.g. `{"name": "Jane Doe", "age": 59, "sportsperson": true}`)

		// ... do something with $person and return a response

Copy link

Contributor

94noniJan 27, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change

	// ... do something with $person and return aresponse
	// ... do something with $person and return ajsonresponse

? as you validate in first step it is a json request content type

Copy link

Contributor

OskarStark commentedJan 27, 2023

I added a "closes" to the PR header

javiereguiluz reviewed

Jan 28, 2023

View reviewed changes

serializer.rst OutdatedShow resolvedHide resolved

serializer.rstShow resolvedHide resolved

Nyholm reviewed

Jan 29, 2023

View reviewed changes

Copy link

Member

Nyholm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Thank you for working on this.

Just a note: I would be nice to mention constructors. How are they being used when deserializing an object?

serializer.rst OutdatedShow resolvedHide resolved

javiereguiluz mentioned this pull request

Feb 16, 2023

[META] Symfony Serializer issues#17912

Open

6 tasks

Copy link

Member

javiereguiluz commentedAug 9, 2024

@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!

Copy link

MemberAuthor

wouterj commentedSep 19, 2024•
edited
Loading

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).

wouterj mentioned this pull request

Sep 19, 2024

[Serializer] Introduce named serializers#20235

Closed

wouterj force-pushed theserializer branch 2 times, most recently from45210b4 to55c4cebCompare

October 20, 2024 23:00

Copy link

MemberAuthor

wouterj commentedOct 20, 2024•
edited
Loading

So here we are... It is not perfect, but I believe it's complete enough to be merged. 🚀 We can iterate upon it after it's fully merged. Thank you very much for the patience this far! 🙏

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 👀 .

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.

wouterj commented

Oct 20, 2024

View reviewed changes

serializer.rst

Comment on lines +1282 to +1435

		:class:`Symfony\\Component\\Serializer\\Normalizer\\CustomNormalizer`
		This normalizer calls a method on the PHP object when normalizing. The
		PHP object must implement :class:`Symfony\\Component\\Serializer\\Normalizer\\NormalizableInterface`
		and/or :class:`Symfony\\Component\\Serializer\\Normalizer\\DenormalizableInterface`.

Copy link

MemberAuthor

wouterjOct 20, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

I find it weird that this is the only built-in normalizer that is not registered by default. Is there a reason for this that we need to explain? (e.g. performance?)

serializer.rst Outdated

Comment on lines 1287 to 1455

		:class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer`
		This normalizer is an alternative to the default ``ObjectNormalizer``.
		It reads the content of the class by calling the "getters" (public
		methods starting with ``get``, ``is`` or ``has``). It will denormalize
		data by calling the constructor and the "setters" (public methods
		starting with ``set``).

		Objects are normalized to a map of property names and values (names are
		generated by removing the ``get`` prefix from the method name and transforming
		the first letter to lowercase; e.g. ``getFirstName()`` -> ``firstName``).

		:class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`
		This is yet another alternative to the ``ObjectNormalizer``. This
		normalizer directly reads and writes public properties as well as
		private and protected properties (from both the class and all of
		its parent classes) by using `PHP reflection`_. It supports calling the
		constructor during the denormalization process.

		Objects are normalized to a map of property names to property values.

Copy link

MemberAuthor

wouterjOct 20, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

So we have 2 older iterations of the ObjectNormalizer still hanging around in the component. Is there any situation where I wouldnot want to use theObjectNormalizer and instead register one of these 2? If not, should we deprecate them (or one of them)? Should we stop documenting them, and hope their usages will slowly extinguish?

I really dislike having to say "yet another alternative" without any concrete example of why you should want to use it.

Copy link

Member

javiereguiluzOct 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Not an expert in this component, but what you say makes sense. Let's keep the good one and deprecate/remove the others.

fabpot requested changes

Oct 21, 2024

View reviewed changes

serializer/custom_name_converter.rst OutdatedShow resolvedHide resolved

serializer/encoders.rst

		All these encoders are enabled by default when using the Serializer component
		in a Symfony application.

		The ``JsonEncoder``

Copy link

Member

fabpotOct 21, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Maybe just (same below):

Suggested change

	The``JsonEncoder``
	``JsonEncoder``

serializer/encoders.rst OutdatedShow resolvedHide resolved

carsonbot added Status: Needs Work and removed Status: Needs Review labels

Oct 21, 2024

wouterj marked this pull request as ready for review

October 21, 2024 06:43

carsonbot added Status: Needs Review and removed Status: Needs Work labels

Oct 21, 2024

wouterj force-pushed theserializer branch from55c4ceb to5628fc8Compare

October 21, 2024 08:11

javiereguiluz reviewed

Oct 22, 2024

View reviewed changes

Copy link

Member

javiereguiluz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Thanks Wouter for a superb effort refactoring the entire Serializer docs 🙇🙇🙇

serializer.rstShow resolvedHide resolved

serializer.rst OutdatedShow resolvedHide resolved

serializer.rstShow resolvedHide resolved

serializer.rst Outdated

Comment on lines 1287 to 1455

		:class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer`
		This normalizer is an alternative to the default ``ObjectNormalizer``.
		It reads the content of the class by calling the "getters" (public
		methods starting with ``get``, ``is`` or ``has``). It will denormalize
		data by calling the constructor and the "setters" (public methods
		starting with ``set``).

		Objects are normalized to a map of property names and values (names are
		generated by removing the ``get`` prefix from the method name and transforming
		the first letter to lowercase; e.g. ``getFirstName()`` -> ``firstName``).

		:class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`
		This is yet another alternative to the ``ObjectNormalizer``. This
		normalizer directly reads and writes public properties as well as
		private and protected properties (from both the class and all of
		its parent classes) by using `PHP reflection`_. It supports calling the
		constructor during the denormalization process.

		Objects are normalized to a map of property names to property values.

Copy link

Member

javiereguiluzOct 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Not an expert in this component, but what you say makes sense. Let's keep the good one and deprecate/remove the others.

javiereguiluz reviewed

Oct 22, 2024

View reviewed changes

serializer.rst OutdatedShow resolvedHide resolved

wouterj force-pushed theserializer branch from5628fc8 tod255417Compare

October 22, 2024 21:30

Copy link

MemberAuthor

wouterj commentedNov 16, 2024

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 ? :)

xabbuh reviewed

Nov 18, 2024

View reviewed changes

serializer.rst OutdatedShow resolvedHide resolved

xabbuh reviewed

Nov 18, 2024

View reviewed changes

serializer.rstShow resolvedHide resolved

Copy link

Member

javiereguiluz commentedNov 19, 2024

@wouterj yes, please ... ship it whenever you can find some time for this. Thanks!

wouterj force-pushed theserializer branch fromd255417 to3907094Compare

November 23, 2024 13:54

wouterj changed the base branch from5.4 to6.4

November 23, 2024 13:54

wouterj force-pushed theserializer branch from3907094 to4e3eacdCompare

November 23, 2024 13:57

Copy link

MemberAuthor

wouterj commentedNov 23, 2024•
edited
Loading

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.