Add support for HTTP request monitoring callback

[ob-stripe]

r? @rattrayalex-stripe
cc @stripe/api-libraries @suadhuskic

Add support for passing a callback that is called after every HTTP request. This can be used for logging, monitoring, stats, or anything else.

Used like this:

$curl = new CurlClient();
$curl->setRequestStatusCallback(function ($rbody, $rcode, $rheaders, $errno, $message, $willBeRetried, $numRetries) {
  // Do whatever
});
\Stripe\ApiRequestor::setHttpClient($curl);

@suadhuskic This is a bit more complex than what you submitted but also more powerful, since it lets you access more information about the request (e.g. the HTTP status code, the request ID in the headers, etc.). I think it would also work for your use case, what do you think?

[ob-stripe]

ptal @rattrayalex-stripe

[rattrayalex-stripe]

Slightly worried about users throwing from within the callback and blocking a retry intentionally or unintentionally, but I don't think it's worth losing sleep over

[suadhuskic]

Doesn't seem like a fun usage from a client perspective knowing all network retry logic is on the Stripe class and now i have to manually set this curl client up before attempting my charge.

Currently I have:

   Stripe::setApiKey('magic');
   Stripe::$maxNetworkRetries = 3;

   $paymentIntent = PaymentIntent::create($requestParams, $requestOptions);

This is why my proposal was what it was in #763 to keep the pattern there. Thank you for quickly putting this up!

[ob-stripe]

Doesn't seem like a fun usage from a client perspective knowing all network retry logic is on the Stripe class and now i have to manually set this curl client up

That's a fair criticism. The max retries number should really be a property of CurlClient since that's the class actually handling the retries. I want to clean up the interfaces of both the Stripe global class and CurlClient, but that will have to wait for a future major version since it would likely include some non-backwards compatible changes.

[ob-stripe]

Released as 7.4.0.

[jmraker]

As a user who alters the CurlClient.php source to add logging it's not quite there. I log the url +parameters of the api call and I don't see a way to do that. It would be nice if it also passed the $opts array.

[ob-stripe]

@jmraker Interesting use case! I think it might be more appropriate to have two callbacks: one before the request with the request properties (method, URL, parameters) and one after the request with the response properties (status code, response body, etc.).

I don't want to rush into things though as I'm planning on some major changes to the HTTP client interface. In the meantime, I think a cleaner workaround that would not require you to modify the library's source code would be to subclass CurlClient:

class LoggingCurlClient extends \Stripe\HttpClient\CurlClient
{
  public function request($method, $absUrl, $headers, $params, $hasFile)
  {
    // log request parameters

    list($rbody, $rcode, $rheaders) = parent::request($method, $absUrl, $headers, $params, $hasFile);

    // log response parameters

    return [$rbody, $rcode, $rheaders];
  }
}

$loggingClient = new LoggingCurlClient();
\Stripe\ApiRequestor::setHttpClient($loggingClient);