Clarify Body Listener Usage in Documentation

[jonmchan]

Can we add clarification and/or an example to the Body Listener documentation section (https://github.com/FriendsOfSymfony/FOSRestBundle/blob/master/Resources/doc/3-listener-support.md#body-listener)? I notice there is no controller example for just using the Body Listener. Is it that the Body Listener must be used with the ParamFetcher listener or the Request Body Converter Listener? If so, can this be explicitly stated in the documentation somewhere? (I apologize in advance if it is there and I just couldn't find it)

While I'm on the topic... I think the Listener Support page in general can use some cleanup. There has been many different listeners that have been added that sometimes interact with each while others can be used in alternative to each other. The other issue is that the names are all very similar - maybe we can add a TOC or definitions section that lists all the different listeners and their purpose in one sentence? Maybe we can categorize them too by what they do?

[lsmith77]

no the BodyListener just overwrites $request->request (ie. where POST data would normally be found). please feel free to add a sentence to the docs to clarify this.

as for the listener docs page. yes. it is indeed a bit confusing and long. maybe its time to split it up and do some interlinking. would you be willing to invest a bit of time into this?

[jonmchan]

After submitting this issue, I spent a few hours going through the source and I understand it much better. That said, I think that other developers should not have to go through the source to understand how to use this. I submitted a PR with some proposed changes... I don't have enough time to work out the entire documentation, but perhaps my PR can be a start and others can get involved in fleshing out the documentation and rewriting it so it is more clear. I think the most unclear issue about it is that the listeners are not categorized but just thrown together (probably in the order they were implemented?). If we categorize the different listeners, it will make the whole thing more clear.

[lsmith77]

yeah .. its all very evolutionary how the different listeners came about and how they were documented.

[ArlingtonHouse]

Related question-- what is the difference between a RequestParam and a QueryParam? Are QueryParams things like page number, sort by, count, etc, and RequestParam things like filters (?email=foo@bar.com) etc? Thanks!

[stof]

QueryParam are coming from the query string ($_GET) while RequestParam are coming from the request body (which is decoded in $_POST for form-url-encoded POST requests)

[lsmith77]

ping

[jonmchan]

Are you pinging me?

[lsmith77]

yeah .. just wondering if you are motivated to revisit the topic. that being said, the docs will soon be on symfony.com .. hoping that this will also entice more people to help on the docs.

[jonmchan]

Sorry - I no longer am working on symfony projects anymore. My work has pulled me off to RoR projects and it doesn't look like i'll be doing symfony anytime soon. So I don't really have the bandwidth to finish up the docs.