[PSR-17] Document what must and mustn’t be set by createServerRequestFromArray?

[Martijn van der Ven]

Hi,

I was recently looking at the latest changes to the PSR-17 proposal made in commit 3166325 [1] and while I agree with the change itself (splitting into two separate methods), my main concern is about the complete removal of the following sentence:

The method and URI of the request SHOULD be derived from the given server parameters.

This was previously the only guidance in the PSR as to what property values should be assigned to the ServerRequest by the factory. Leaving this completely open would, I believe, make different factory implementations incompatible with each other.

Implementations might make #createServerRequestFromArray() follow #createServerRequest() and only set the method and URI based on the array. Others might assign the server parameters, which I would argue is the expected (but undocumented) behaviour of createServerRequestFromArray versus createServerRequest. Library users switching implementation could run into this difference when #getServerParams() suddenly starts returning unexpected different results.

As the server parameters are read-only, a more dangerous implementation difference could be the assignment of headers to the ServerRequest based on what they find in the provided array. ($_SERVER includes HTTP headers as HTTP_* values.) As the documentation does not mention headers, implementations can make their own choice on what they will do. If a library user is used to having to add the headers themselves, they might loop over some soft of header collection and call #withAddedHeader() on the ServerRequest. In the case of an implementation that does not add headers, this will work fine, while the user otherwise ends up with a load of duplicated headers on their ServerRequest.

I would propose clarifying the documentation on #createServerRequestFromArray() to specify what must and mustn’t be set on the newly created ServerRequest. The following things come to mind:

• Specify that the passed $server MUST or MUST NOT be set as the result for #getServerParams(). Do not leave this up to the interpretation of the implementer.
  
• Specify that the results for #getMethod() and #getUri() MUST be set based on $server. This is currently implied by the documented @throws only.
  
• Specify what other information MUST or MUST NOT be extracted. E.g. header information, which is available in $_SERVER but should either always be added by implementers or never as it otherwise makes for different ServerRequest instances that need different follow-up.
  

I do not frequent mailing lists a lot, so if I have made any mistakes in bringing this here, do let me know.

M.

[1]: https://github.com/php-fig/fig-standards/commit/31663251d3fc37653ab1441035a8ed187736b2b1