[Serializer] Name Converter

[dunglas]

Q	A
Doc fix?	no
New docs?	yes symfony/symfony#13120
Applies to	2.7

This is the documentation for the Serializer Name Converter feature.

[timglabisch]

the " ' " is wrong?

[wouterj]

It's to make properties or getters a possesion of the PHP class. However, if I'm correct you should use 's for a single owner (one PHP class) and just ' for multiple owners (PHP classes' properties or getter).

Even more, since both objects are things and not humans, I think using ... of ... is better: "different than properties, getter or setter methods of the PHP class"

[wouterj]

Thank you! It's great to see a doc PR when a new code PR is opened.

I've decorated it with many comments. Not real big things, though. The more doc PRs you'll create, the less comments you'll get 😉

[dunglas]

@wouterj thank you very much for your review! I've changed most of the things you pointed out. I've replied to your comments when changes seem not needed to me.

I'll try to provide a book entry for the serialization component soon!

[dunglas]

I've also switched the term "underscore separated" by "snake_case".

[wouterj]

I'll try to provide a book entry for the serialization component soon!

I like your enthousiasm, but I'm not sure if I like creating a book chapter. I don't think the Serializer component is a component that should have a book chapter. Book chapters should only list the basic things of Symfony imo. I think it's better if you create an issue first, so other doc maintainers can give their opinions as well.

[dunglas]

I'll create an issue. When symfony/symfony#13107 will be merged, it can be cool to have a chapter in the book explaining the basics of serialization (add annotations to the entity, or XML or YAML mappings, then use $this->get('serializer') in the controller).
Something similar (but shorter) to the validation chapter.

[stof]

Should the documentation for the previous feature really be removed from the 2.7 doc ?

[dunglas]

@stof I'm not aware of the policy about the doc for deprecated features.

[dunglas]

@xabbuh we are speaking about ~2 more lines of code (and with a broader functionality set: you can convert all attributes).
I think it's confusing for users to have different manners to do the same thing (using the setCamelizedAttributes() or using the new system). Also, it makes harder to get a full knowledge of the tool.

Another drawback with keeping setCamelizedAttributes() is more code to maintain and issues to reply (ex: symfony/symfony#12212 - possible with the new system, not with setCamelizedAttributes()).

[javiereguiluz]

I don't think it's OK to use a real company name and address. What about using ACME as the rest of the documentation?

[dunglas]

Can you gimme details for the Acme org (the fake address used)?

[javiereguiluz]

What about the following?

{ "org_name": "Acme Inc.", "org_address": "123 Main Street" }

[wouterj]

We don't use an address in the docs, something like "426 Jordy Lodge, Cartwrightshire, SC 88120-6700" will do (just a random address generated by Faker).

Or @javiereguiluz's proposal (which is maybe even better)

[dunglas]

I've fixed reported problems. I've used a fake french company name instead of Acme Inc. (same spirit but located in Lille France for the nod).

[javiereguiluz]

@dunglas I'm really sorry to insist, but I don't think it's OK to keep using Euratechnologies as part of the address and I also don't think that using Lille or France is OK. In my opinion, we should use a completely fake and international-looking address.

PS: don't get me wrong: I work for a french company, I know a lot of french guys and I love french culture ... but Symfony docs are international and I think they should stay that way. But let's see what other doc reviewers think.

[dunglas]

@javiereguiluz Euratechnologies is a big tech center where hundred of companies including Microsoft, IBM and Cap Gemini have offices. But if you think its really a problem I push a commit with the Acme things you proposed...

[wouterj]

I think this one can be merged now

[xabbuh]

I think the spaces around the / should be removed.

[dunglas]

Issues found by @xabbuh fixed.

[weaverryan]

Thanks Kévin! I'm excited to try out all the new serializer features in 2.7 - much needed imo!