[HttpClient] Support file uploads by nesting resource streams in body option

[nicolas-grekas]

Q	A
Branch?	6.3
Bug fix?	no
New feature?	yes
Deprecations?	no
Tickets	-
License	MIT
Doc PR	-

This PR makes it easy to upload files using multipart/form-data.

Nesting streams in option "body" is all one needs to do:

$h = fopen('/path/to/the/file' 'r');
$client->request('POST', 'https://...', ['body' => ['the_file' => $h]]);

By default, the code will populate the filename using the base-name of the opened file.
It's possible to override this by calling stream_context_set_option($h, 'http', 'filename', 'the-name.txt').

When forwarding an HTTP request coming either from the native http stream wrapper or from Symfony's StreamableInterface, the code will forward the content-type. It's also possible to set the content-type using stream_context_set_option($h, 'http', 'content_type', 'my/content-type').

When possible, the code will generate a Content-Length header. This enables the destination server to reject the request early if it's too big and it allows tracking the progress of uploads on the client-side.

[stof]

why is this a static variable instead of a local variable ? Do we really need a hidden global state here ?

[nicolas-grekas]

We need this to generate a random boundary without consuming too much entropy from the system.
We don't care about the hidden state because this is just a random string that is updated after use.

[stof]

I'm not against using a variable. But it could be a normal one, so that each call to prepareBody is independant.

[stof]

Or you should not reuse that cookie when generating the multipart boundary that is visible to the outside.

[nicolas-grekas]

Each call is already independent from the previous one thanks to the randomization provided by the xxh128 hashing.
I don't want to call random_bytes all the time.

[stof]

shouldn't we close the resource once we are done reading it ? Due to the async nature of the component, it would be very hard to keep the ownership of the resource in the caller code while avoiding to close it too early (it must not be closed until http-client is done with it).
Guzzle has a feature allowing to create a body from a stream, and it takes ownership of the resource for such reason.

[nicolas-grekas]

I'd prefer not. The current code allows the outer scope to rewind the stream if needed.

[stof]

but how do you handle closing those streams to avoid leaking them ?

[nicolas-grekas]

I added unset($body[$i]); and $h = null at the end of the generator. Stream resources are auto-closed by PHP when released from memory.

[fabpot]

Thank you @nicolas-grekas.