PHP 8.5: Curl: New curl_multi_get_handles function

The Curl extension in PHP 8.5 adds a new function named curl_multi_get_handles that returns an array of CurlHandle objects from a CurlMultiHandle object.

The new curl_multi_get_handles function complements the existing functions to add (curl_multi_add_handle) and remove (curl_multi_remove_handle) CurlHandle objects into/from a CurlMultiHandle object.

Without this function, to retrieve CurlHandle objects added to a CurlMultiHandle, the application had to maintain a list of CurlHandle objects, preferably in a WeakMap. With a WeakMap, CurlHandle objects can be destroyed freely without counting the use in a WeakMap object as a reference.

---

$cm = curl_multi_init();
curl_multi_get_handles($cm);
// Empty array

$ch1 = curl_init('https://example.com/foo');
$ch2 = curl_init('https://example.com/bar');

curl_multi_add_handle($cm, $ch1);
curl_multi_add_handle($cm, $ch2);

curl_multi_get_handles($cm);
// [$ch1, $ch2]

curl_multi_get_handles function synopsis

/**
 * Get a list of CurlHandle objects in a given
 * CurlMultiHandle object
 *
 * @param CurlMultiHandle $multi_handle
 * @return array
 */
function curl_multi_get_handles(CurlMultiHandle $multi_handle): array {}

• The curl_multi_get_handles function is declared in the global namespace.
• If the CurlMultiHandle contains no CurlHandle objects, it returns an empty array.

Backward Compatibility Impact

Unless an application declares its own curl_multi_get_handles function, this change does not cause any backward compatibility issues.

Note that the libcurl function curl_multi_get_handles provides similar functionality, but it is only available on libcurl 8.4 and later. The PHP's curl_multi_get_handles implementation does not depend on this libcurl function.

The curl_multi_get_handles function cannot be easily polyfilled using user-land PHP. However, it is possible to mimic this functionality by storing the CurlHandle objects separately in a PHP array, or ideally in a WeakMap.

$cm = curl_multi_init();
$handleMap = new WeakMap();

$ch1 = curl_init('https://example.com/foo');
$ch2 = curl_init('https://example.com/bar');

curl_multi_add_handle($cm, $ch1);
curl_multi_add_handle($cm, $ch2);
$handleMap[$ch1] = 1;
$handleMap[$ch2] = 2;

$handles = [];
foreach($handleMap as $ch => $noop) {
    $handles[] = $ch;
}

$handles;
// [$ch1, $ch2]

---

curl_multi_get_handles Implementation