RFC1867 (multipart/form-data) PUT requests

Hi Ben, Hi Rowan

Introduce a new function (currently named populate_post_data()) to
read the input stream and populate the $_POST and $_FILES
superglobals.

How about "request_form_populate_globals"?

The word "form" seems a bit out of place (even though it appears in
both multipart/form-data and application/x-www-form-urlencoded),
because this function is mainly targeted at PUT/PATCH requests for
REST APIs. Maybe request_body_populate_globals?

Another option for the name: populate_multipart_form_data().

I avoided the term "multipart" because the function technically also
works for application/x-www-form-urlencoded requests. It's less
necessary for the reasons outlined in my previous email, but it would
allow for consistent handling of such requests for all HTTP methods.

Some people on GitHub voiced that they would prefer an INI setting.
Therefore I will create an RFC accordingly.

I know this issue comes up enough because it’s confusing to developers that there’s not a $_PUT, etc., but I’m not a fan of introducing something new that populates globals.

While I’ve never used application/x-www-form-urlencoded data for PUT requests (because I don’t think it’s a proper content-type for the semantics of PUT), I do see how this content-type could be used with PATCH, and I also don’t want to rule-out use cases of it for PUT or any other HTTP method.

In the past, I’ve used something like the following to solve this:

parse_str(file_get_contents('php://input'), $data);

I haven’t looked up how any of the frameworks solve this, but I would be willing to bet they also do something similar.

Rather than implementing functionality to populate globals, would you be interested in introducing some new HTTP request functions. Something like:

http_request_body(): string
http_parse_query(string $queryString): array

http_request_body() would return the raw body and would be the equivalent of calling file_get_contents('php://input'). Of special note is that it should always return the raw body, even if $_POST is populated, for the sake of consistency and reducing confusion.

http_parse_query() would be the opposite of http_build_query() and would return a value instead of requiring a reference parameter, like parse_str().

While these don’t address the confusion users face by not having a $_PUT superglobal, I’d prefer not to overload the superglobals. Maybe we can update the documentation to encourage use of these new functions instead of the superglobals?

We also might want to introduce something like http_query_string(): string that always returns the raw query string, instead of requiring use of the superglobal $_SERVER['QUERY_STRING'].

Cheers,
Ben

As a userland/library developer I much prefer this approach, but please also include http_uploads() (name/signature TBD), returning an array of file uploads using a structure akin to what $_POST (or http_parse_query) gives, based on the field name, rather than the current scenario where the presence of square brackets radically changes the structure of the $_FILES array.

My initial thought was that perhaps the leaf entities in said array could be a subclass of SplFileInfo referencing the uploaded temporary file, with additional read-only properties for the extra upload-related attributes - but really the important thing is just having a sane, consistent structure. Having an object rather than an array with constant keys would be a nice addition, but is much less important.

Cheers

Stephen

Hi Ben

Hi Ben, Hi Rowan

Introduce a new function (currently named populate_post_data()) to
read the input stream and populate the $_POST and $_FILES
superglobals.

In the past, I’ve used something like the following to solve this:

parse_str(file_get_contents('php://input'), $data);

I haven’t looked up how any of the frameworks solve this, but I would be willing to bet they also do something similar.

Rather than implementing functionality to populate globals, would you be interested in introducing some new HTTP request functions. Something like:

http_request_body(): string
http_parse_query(string $queryString): array

http_request_body() would return the raw body and would be the equivalent of calling file_get_contents('php://input'). Of special note is that it should always return the raw body, even if $_POST is populated, for the sake of consistency and reducing confusion.

http_parse_query() would be the opposite of http_build_query() and would return a value instead of requiring a reference parameter, like parse_str().

The problem is that the content stream for multipart/form-data is
expected to be big, as in possibly multiple gigabytes big. We can't
use http_request_body() to return the entire content as a string at
once. The current RFC1867 implementation reads and operates in chunks,
i.e. appends it to a file or to a string, depending on the content
part. It never has to hold on to the entire content in memory.
http_request_body() also can't return the content of the request again
after it has been consumed, because that's not how the HTTP protocol
works. We would need to buffer the content somewhere when reading it
for the first time, which again we can't do because it may be very
big.

It may be possible to pass the fopen('php://input', 'r') stream to
this function and let it consume it. However, as mentioned in my
original e-mail this requires some changes to how RFC1867 requests are
handled. Currently, it calls sapi_module.read_post() which directly
reads from the TCP socket. Instead, we'd need to read from the stream,
possibly in addition so that the general case is not degraded in terms
of performance. I'll verify if this is an option, and whether the
changes are (too) big. However, I don't suspect there to be a lot of
use-cases for this as RFC1867 is primarily used for requests and not
for responses, so you wouldn't usually need to parse this type of
content from some other source.

As for returning the parsed values as non-globals, that's entirely
possible. However, it's inconsistent with how requests are currently
handled. The values will need to be passed around manually and kept
alive, but the function still modifies global state (i.e. the input
stream, whether that's sapi_module.read_post() or php://input). I
don't believe it will be common to call this function more than once
per request, and thus decoupling the state is not really necessary.

Ilija