Streaming requests

[richardm-stripe]

Reviews

r? @dcr-stripe @ob-stripe
cc @stripe/api-libraries

Summary

This PR adds "streaming" support to our HttpClient.

Similar to PRs in stripe-node, stripe-java, stripe-ruby, stripe-python, and stripe-go.

Up until now, all Stripe methods return JSON; stripe-php buffers the JSON into memory, parses it and constructs a StripeObject of the appropriate class before returning it to the user.

We plan soon to release a /pdf method that will violate this pattern. It will return bytes that the user will likely want to write directly to a file or transmit to another server, without buffering into memory.

Towards that end this pr introduces a requestStreaming method.

requestStreaming's implementation passes \CURLOPT_RETURNTRANSFER = false and a callback function
in \CURLOPT_WRITEFUNCTION, that curl will then call with bytes from the body.

requestStreaming exposes a similar interface to the caller. The user passes in a callback $readBodyChunk, which requestStreaming will call with "chunks" from a successful request body as they arrive, before returning.

Example of what the end-user experience will look like:

$foo = FooResource::retrieve('foo');
$fileHandle = \fopen("/tmp/foo.pdf", 'wb');
$readBodyChunk = function ($chunk) use (&$fileHandle) {
    \fwrite($fileHandle, $chunk);
};
$foo->pdf($readBodyChunk);
\fclose($fileHandle);

or see the test

I think in an ideal world, we'd return a PSR-7-compatible "stream" interface instead -- users have requested our responses be more PSR-7 compatible in the past. This, though, is the approach I think is most compatible with our current CurlClient implementation.

[dcr-stripe]

Overall I think this looks good and makes sense. Left a few comments. Thanks for putting together the test infrastructure! Curious what @ob-stripe thinks as well.

[richardm-stripe]

r? @dcr-stripe this is ready for another review - I removed a test case that was unavoidably flaky and addressed feedback from the previous review

[dcr-stripe]

LGTM! Thanks Richard! 🚢

[ob-stripe]

LGTM as well.

Not a huge fan of having to spin up a new process in tests for the test server, but it works and I can't think of a better way.