Skip to content

Fixes #4272 Documentation for the new PropertyNormalizer #4308

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

Fixes #4272 Documentation for the new PropertyNormalizer #4308

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
421aa41
ref #4272 Documentation for the new PropertyNormalizer introduced in …
mnapoli Oct 9, 2014
4815c4a
Introduction about normalizers
mnapoli Oct 18, 2014
6868a19
Updated the rendering of the list
mnapoli Oct 9, 2014
629c8ac
Added line returns…
mnapoli Nov 1, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions components/serializer.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,12 @@ which Encoders and Normalizer are going to be available::

$serializer = new Serializer($normalizers, $encoders);

There are several normalizers available, e.g. the
:class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer` or the
:class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`.
To read more about them, refer to the "Normalizers" section in this page.
Copy link
Member

Choose a reason for hiding this comment

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

This is just a minor issue, but I think it would be really great to link this to the "Normalizers" section.

All the examples shown below use the GetSetMethodNormalizer.

Serializing an Object
---------------------

Expand Down Expand Up @@ -238,6 +244,30 @@ When serializing, you can set a callback to format a specific object property::
$serializer->serialize($person, 'json');
// Output: {"name":"cordoval", "age": 34, "createdAt": "2014-03-22T09:43:12-0500"}

Normalizers
-----------

There are several types of normalizers available::
Copy link
Member

Choose a reason for hiding this comment

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

I don't know this document very well, but do we explain what normalizers are and what they do somewhere else? Otherwise, we first need to do that in this section

Copy link
Contributor Author

Choose a reason for hiding this comment

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

No I have not seen any explanation :( I think it was because there was only 1 normalize before, so that's why all the examples use the same. The behavior of the "GetSet" normalizer was kind of considered "default".

Copy link
Member

Choose a reason for hiding this comment

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

Well, we have a short part about normalizing/denormalizing in the introduction. Maybe this should be expanded a bit in this new section before introducing the concrete normalizers.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I've added a small introduction in the Usage part.

Like @xabbuh said, what normalizers do is explained at the beginning of the article. What I've added is to make more explicit that there is more than 1 normalizer (because all the examples use the original normalizer).

Copy link
Member

Choose a reason for hiding this comment

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

You will have to remove one colon. Otherwise, the following item is treated as a PHP code block.


* The :class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer`
Copy link
Member

Choose a reason for hiding this comment

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

I prefer to use the definition list syntax here:

The :class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer`
    This normalizer [...]

The :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`
    [...]

Copy link
Member

Choose a reason for hiding this comment

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

I would then also omit the article ("The").


This normalizer reads the content of the class by calling the "getters" (public
Copy link
Contributor

Choose a reason for hiding this comment

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

would prefer The GetSetMethodNormalizer normalizer reads ....

Copy link
Member

Choose a reason for hiding this comment

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

I think it's too verbose and doesn't add much value.

Copy link
Contributor

Choose a reason for hiding this comment

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

ok

methods starting with "get"). It will denormalize data by calling the constructor
and the "setters" (public methods starting with "set").

Objects are serialized to a map of property names (method name stripped of the "get"
prefix and converted to lower case) to property values.
Copy link
Member

Choose a reason for hiding this comment

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

Both paragraphs have to be indented by two spaces. Otherwise, they will be treated as quotes.


* The :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`

.. versionadded:: 2.6
The :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`
class was introduced in Symfony 2.6.

This normalizer directly reads and writes public properties as well as
**private and protected** properties. Objects are serialized to a map of
property names to property values.
Copy link
Member

Choose a reason for hiding this comment

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

same here


Handling Circular References
----------------------------

Expand Down