[PSR-7] Make getHeaders() and getHeader() consistent

[Bernhard Schussek]

Hi all,

Currently, the result of MessageInterface::getHeaders() and getHeader() is inconsistent. Given their naming, I would expect that:

$message->getHeaders()[$k] === $message->getHeader($k)

However, that's not the case, as getHeaders()[$k] returns an array of strings, while getHeader($k) returns the concatenated value, i.e. a string.

I think this should be fixed by changing either of the two methods to match the other. The least intrusive fix seems to be to change getHeaders() to return the concatenated values. Then:

$message->getHeaders()[$k] === $message->getHeader($k) - string concatenated with ","

$message->getHeaderLines($k) - string[]

PR: https://github.com/php-fig/fig-standards/pull/491

Cheers,

Bernhard

--

Bernhard Schussek
Blog: http://webmozarts.com
Twitter: http://twitter.com/webmozart

[Matthew Weier O'Phinney]

On Apr 7, 2015 8:06 AM, "Bernhard Schussek" <bsch...@gmail.com> wrote:
>
> Hi all,
>
> Currently, the result of MessageInterface::getHeaders() and getHeader() is inconsistent. Given their naming, I would expect that:
>
> $message->getHeaders()[$k] === $message->getHeader($k)
>
> However, that's not the case, as getHeaders()[$k] returns an array of strings, while getHeader($k) returns the concatenated value, i.e. a string.
>
> I think this should be fixed by changing either of the two methods to match the other. The least intrusive fix seems to be to change getHeaders() to return the concatenated values. Then:
>
> $message->getHeaders()[$k] === $message->getHeader($k) - string concatenated with ","
> $message->getHeaderLines($k) - string[]
>
> PR: https://github.com/php-fig/fig-standards/pull/491

I've responded in on the pull request, but want to go into more detail. The naming and signature may appear inconsistent, but was chosen to optimize for the most common use cases.

- getHeaders() is primarily used when emitting headers. At that time, you want the raw structure (array of values) so you can either emit separate lines for each value, or choose the correct concatenation string (as not all headers use comma concatenation).
- getHeader() is primarily used to introspect an individual header, and the expectation will be to treat the values as a whole (e.g. testing an Accept header or an Authorization header).
-getHeaderLines() exists for when you expect multiple values for a given header, and want them delivered separately.

Changing getHeaders to return an array of strings would go counter to its already established purpose, and would require a new method for retrieving the raw structure. Additionally, the array of string values approach would complicate the most common use case (emitting headers, as now you need to be cognizant of the multiple methods and their purposes) and complicate implementations (they would potentially need to know how to concatenate each header). If implemented in the same way as getHeader, and with the same restrictions (only return comma concatenated strings), it would be utterly useless in the majority of situations.

The point is that while symmetry may be a consideration, we also need to look at developer experience and common use cases, which is what the current proposal has done.

>
> Cheers,
> Bernhard
>
> --
> Bernhard Schussek
> Blog: http://webmozarts.com
> Twitter: http://twitter.com/webmozart
>

> --
> You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
> To post to this group, send email to php...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAHjTTqNxtw_tx0cNqOgbQgozQnYjmkbtnBd5CRwjUnyDk3J3cg%40mail.gmail.com.
> For more options, visit https://groups.google.com/d/optout.

[Bernhard Schussek]

Ok. We can also fix this by taking an alternative route:

getHeaders() -> return string[][] (as done right now)

getHeaderLines() -> rename to getHeader()

getHeader() -> rename to getHeaderAsString() (or similar)

Then $message->getHeaders()[$k] === $message->getHeader($k) holds and $message->getHeaderAsString() returns the concatenated version.

I'm indifferent to which fix we apply, I just want the inconsistency removed.

--

Bernhard Schussek
Blog: http://webmozarts.com
Twitter: http://twitter.com/webmozart

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAJp_myXbvmQqGGrMz_cG5h4LO9%2B7OSc7%2BCUimeWuegUYt8zWNg%40mail.gmail.com.

[Paul M. Jones]

> On Apr 7, 2015, at 10:06, Bernhard Schussek <bsch...@gmail.com> wrote:
>
> Ok. We can also fix this by taking an alternative route:
>
> getHeaders() -> return string[][] (as done right now)
> getHeaderLines() -> rename to getHeader()
> getHeader() -> rename to getHeaderAsString() (or similar)
>
> Then $message->getHeaders()[$k] === $message->getHeader($k) holds and $message->getHeaderAsString() returns the concatenated version.
>
> I'm indifferent to which fix we apply, I just want the inconsistency removed.

Perhaps something like this:

<https://github.com/php-fig/fig-standards/pull/493>

My apologies to MWOP for this Johnny-come-lately suggestion. As I have stated elsewhere, I felt I was the only one who found the existing inconsistency grating, and for that reason was willing to submit to the justifications stated in the meta-document. But now that someone else finds the same, I'd like address it again. (It may still end up that "no change" would best.)


--
Paul M. Jones
pmjo...@gmail.com
http://paul-m-jones.com

Modernizing Legacy Applications in PHP
https://leanpub.com/mlaphp

Solving the N+1 Problem in PHP
https://leanpub.com/sn1php