CSV-encoding header documentation seems to be a bit misleading

[on3iro]

Hey,

I just started using the CSVEncoder and hat some trouble getting it to work with flat data.
The no_headers flag and its description are very misleading in my opinion.

I wanted to create some simple csv like this:

header1;header2;header3
1;a;x
2;b;y
3;c;z

However from the docs it was really hard to figure out how to specify my custom headers, because of the way the conding handles nested data:

$data = [
   [header1, header2, header3]
   [1, a, x],
   [2, b, y],
   [3, c, y]
]

This would not work, because the encoder would automatically set the headers to the surrounding arrays indices [0,1,2].

If I had written this instead:

$data = [
    "header1" => [1,2,3],
    "header2" => [a,b,c],
    ...
]

I would get nested headers instead.

So the solution for this would be to set the no_headers => true flag for the context.
This makes sense if you think about how CSV works, but especially the description "Disables header in the encoded CSV" makes my brain think along the lines "oh, no headers at all" (which of course is nonsense).

I would probably add something along the lines "Disable automatic headers. Use the first data row instead" and maybe add an example, instead.

I can create a PR with an example and suggested documentation if that helps :)

[javiereguiluz]

Please, describe the problems that you found and, if possible, the things you'd change or improve. Thanks! (and please, don't use strong language like "irritating", "awful", etc. ... this is voluntary work performed by volunteers, so they deserve to be treated well. Thanks!).

Original comment no longer makes sense because the PR description was updated with examples. Thanks!

[on3iro]

sorry accidentally pressed enter

[on3iro]

@javiereguiluz I added a few more lines to the issue, sorry for prematurely submitting :)

[on3iro]

Sorry for using the word "irritating" - it wasn't meant offensive in any way, but I can see how one could interpret it that way :)

[javiereguiluz]

Theo, thanks a lot for reporting this issue ... and for your quick reaction changing that term. Hopefully this will be reviewed soon and we can improve the reported problem. Cheers!

[carsonbot]

Thank you for this issue.
There has not been a lot of activity here for a while. Has this been resolved?

[carsonbot]

Hello? This issue is about to be closed if nobody replies.

[on3iro]

no, I think the point still stands (at least I don't know if anything has happened in that regard since my initial submission)

[javiereguiluz]

Closing in favor of #17912, a meta-issue that groups all pending serializer-related issues so we can easily check them.