PHP 8.2: New curl_upkeep function

PHP 8.2 adds a new function to the Curl extension called curl_upkeep. curl_upkeep function calls curl_easy_upkeep() in libcurl, the underlying C library that PHP Curl extension uses.

curl_upkeep() function performs upkeep work to keep a Curl connection alive. Not all connection types Curl integrates support connection upkeep. Currently, only HTTP/2 connections support connection upkeep.

Connection upkeep is usually done by sending a small amount of traffic to keep the connection alive. For HTTP/2, the connection is kept alive by sending an HTTP/2 PING frame.

This function is only available if the Curl extension is compiled with libcurl version 7.62 or later. Most up to date operating systems and distributions provide a libcurl version newer than 7.62.

Function synopsis

function curl_upkeep(CurlHandle $handle): bool {
}

Since PHP 8.0, all Curl functions return/accept CurlHandle objects instead of traditional PHP resource objects.

If the connection does not provide any upkeep mechanisms, if the Curl connection is not established, or is already closed, the function silently ignores the call and does not emit any errors.

Backwards Compatibility Impact

curl_upkeep is a new function added to the Curl extension in PHP 8.2. Because it uses the underlying curl_easy_upkeep function in libcurl C library, it is not possible to polyfill the functionality in user-land PHP.

Curl is generally configured to reuse connections where possible (and unless otherwise prohibited with CURLOPT_FORBID_REUSE option), and with a long enough keep-alive time, the need for the curl_upkeep() function is not significant.

---

Implementation