Add new curl_upkeep() function

NEWS

@@ -12,6 +12,7 @@ PHP                                                                        NEWS
 
 - Curl:
   . Added new constants from cURL 7.62 to 7.80. (Pierrick)
+  . New function curl_upkeep(). (Pierrick)
 
 - MBString:
   . Backwards-compatible mappings for 0x5C/0x7E in Shift-JIS are restored,

UPGRADING

@@ -77,6 +77,7 @@ PHP 8.2 UPGRADE NOTES
   . Added CURLINFO_EFFECTIVE_METHOD option and returning the effective
     HTTP method in curl_getinfo() return value.
   . Exposed multiple new constants from libcurl 7.62 to 7.80.
+  . Added new function curl_upkeep() to perform any connection upkeep checks.
 
 - OCI8:
   . Added an oci8.prefetch_lob_size directive and oci_set_prefetch_lob()
@@ -174,6 +175,9 @@ PHP 8.2 UPGRADE NOTES
 6. New Functions
 ========================================
 
+- Curl:
+  . curl_upkeep() (libcurl >= 7.62.0)
+
 - Reflection:
   . ReflectionFunction::isAnonymous()
   . ReflectionMethod::hasPrototype()

ext/curl/curl.stub.php

@@ -54,6 +54,10 @@ function curl_getinfo(CurlHandle $handle, ?int $option = null): mixed {}
 /** @refcount 1 */
 function curl_init(?string $url = null): CurlHandle|false {}
 
+#if LIBCURL_VERSION_NUM >= 0x073E00 /* Available since 7.62.0 */
+function curl_upkeep(CurlHandle $handle): bool {}
+#endif
+
 function curl_multi_add_handle(CurlMultiHandle $multi_handle, CurlHandle $handle): int {}
 
 function curl_multi_close(CurlMultiHandle $multi_handle): void {}

ext/curl/curl_arginfo.h

@@ -1,5 +1,5 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: 3abf3f6d5dfb14d2e22ebf5730a869e2c17c7958 */
+ * Stub hash: 1bd8a84a4aa80912463ea76d08f64d3c2cf4c0db */
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_curl_close, 0, 1, IS_VOID, 0)
 	ZEND_ARG_OBJ_INFO(0, handle, CurlHandle, 0)
@@ -49,6 +49,12 @@ ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_curl_init, 0, 0, CurlHandle,
 	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, url, IS_STRING, 1, "null")
 ZEND_END_ARG_INFO()
 
+#if LIBCURL_VERSION_NUM >= 0x073E00 /* Available since 7.62.0 */
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_curl_upkeep, 0, 1, _IS_BOOL, 0)
+	ZEND_ARG_OBJ_INFO(0, handle, CurlHandle, 0)
+ZEND_END_ARG_INFO()
+#endif
+
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_curl_multi_add_handle, 0, 2, IS_LONG, 0)
 	ZEND_ARG_OBJ_INFO(0, multi_handle, CurlMultiHandle, 0)
 	ZEND_ARG_OBJ_INFO(0, handle, CurlHandle, 0)
@@ -144,6 +150,9 @@ ZEND_FUNCTION(curl_exec);
 ZEND_FUNCTION(curl_file_create);
 ZEND_FUNCTION(curl_getinfo);
 ZEND_FUNCTION(curl_init);
+#if LIBCURL_VERSION_NUM >= 0x073E00 /* Available since 7.62.0 */
+ZEND_FUNCTION(curl_upkeep);
+#endif
 ZEND_FUNCTION(curl_multi_add_handle);
 ZEND_FUNCTION(curl_multi_close);
 ZEND_FUNCTION(curl_multi_errno);
@@ -179,6 +188,9 @@ static const zend_function_entry ext_functions[] = {
 	ZEND_FE(curl_file_create, arginfo_curl_file_create)
 	ZEND_FE(curl_getinfo, arginfo_curl_getinfo)
 	ZEND_FE(curl_init, arginfo_curl_init)
+#if LIBCURL_VERSION_NUM >= 0x073E00 /* Available since 7.62.0 */
+	ZEND_FE(curl_upkeep, arginfo_curl_upkeep)
+#endif
 	ZEND_FE(curl_multi_add_handle, arginfo_curl_multi_add_handle)
 	ZEND_FE(curl_multi_close, arginfo_curl_multi_close)
 	ZEND_FE(curl_multi_errno, arginfo_curl_multi_errno)

ext/curl/interface.c

@@ -3989,3 +3989,25 @@ PHP_FUNCTION(curl_pause)
 	RETURN_LONG(curl_easy_pause(ch->cp, bitmask));
 }
 /* }}} */
+
+#if LIBCURL_VERSION_NUM >= 0x073E00 /* Available since 7.62.0 */
+/* {{{ perform connection upkeep checks */
+PHP_FUNCTION(curl_upkeep)
+{
+	CURLcode	error;
+	zval		*zid;
+	php_curl	*ch;
+
+	ZEND_PARSE_PARAMETERS_START(1, 1)
+		Z_PARAM_OBJECT_OF_CLASS(zid, curl_ce)
+	ZEND_PARSE_PARAMETERS_END();
+
+	ch = Z_CURL_P(zid);
+
+	error = curl_easy_upkeep(ch->cp);
+	SAVE_CURL_ERROR(ch, error);
+
+	RETURN_BOOL(error == CURLE_OK);
+}
+/*}}} */
+#endif

ext/curl/tests/curl_upkeep_001.phpt

@@ -0,0 +1,27 @@
+--TEST--
+curl_upkeep() function
+--EXTENSIONS--
+curl
+--SKIPIF--
+<?php
+if (curl_version()['version_number'] < 0x073e00) die('skip requires curl >= 7.62.0');
+?>
+--FILE--
+<?php
+
+$url = "https://example.com";
+
+$ch = curl_init();
+curl_setopt($ch,CURLOPT_URL,$url);
+curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
+curl_setopt($ch,CURLOPT_HTTP_VERSION,CURL_HTTP_VERSION_2_0);
+curl_setopt($ch,CURLOPT_SSL_VERIFYPEER,false);
+curl_setopt($ch, CURLOPT_UPKEEP_INTERVAL_MS, 200);
+if (curl_exec($ch)) {
+    usleep(300);
+    var_dump(curl_upkeep($ch));
+}
+curl_close($ch);
+?>
+--EXPECT--
+bool(true)