ext/curl: Add CURLOPT_PREREQFUNCTION

Curl >= 7.80.0 supports declaring a function for `CURLOPT_PREREQFUNCTION` option
that gets called after Curl establishes a connection (including the TLS handshake
for HTTPS connections), but before the actual request is made.

The callable must return either `CURL_PREREQFUNC_OK` or `CURL_PREREQFUNC_ABORT` to
allow or abort the request.

This adds support for it to PHP with required ifdef.

 - libc: https://curl.se/libcurl/c/CURLOPT_PREREQFUNCTION.html

Author: Ayesh

UPGRADING

@@ -186,6 +186,12 @@ PHP 8.4 UPGRADE NOTES
   . curl_version() returns an additional feature_list value, which is an
     associative array of all known Curl features, and whether they are
     supported (true) or not (false).
+  . Added CURLOPT_PREREQFUNCTION option which accepts a callable that gets
+    called after a connection is established (including TLS handshake), but
+    before the request is made. The function is called with the CurlHandle
+    object, primary IP, local IP, primary port, and the local port, and it
+    must return CURL_PREREQFUNC_OK or CURL_PREREQFUNC_ABORT to allow or abort
+    the request.
 
 - Date:
   . Added static methods
@@ -588,6 +594,11 @@ PHP 8.4 UPGRADE NOTES
 - Core:
   . PHP_OUTPUT_HANDLER_PROCESSED.
 
+- Curl:
+  . CURLOPT_PREREQFUNCTION.
+  . CURL_PREREQFUNC_OK.
+  . CURL_PREREQFUNC_ABORT.
+
 - Intl:
   . The IntlDateFormatter class exposes now the new PATTERN constant
     reflecting udat api's UDAT_PATTERN.

ext/curl/curl.stub.php

@@ -3485,6 +3485,21 @@
  * @cvalue CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256
  */
 const CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 = UNKNOWN;
+/**
+ * @var int
+ * @cvalue CURLOPT_PREREQFUNCTION
+ */
+const CURLOPT_PREREQFUNCTION = UNKNOWN;
+/**
+ * @var int
+ * @cvalue CURL_PREREQFUNC_OK
+ */
+const CURL_PREREQFUNC_OK = UNKNOWN;
+/**
+ * @var int
+ * @cvalue CURL_PREREQFUNC_ABORT
+ */
+const CURL_PREREQFUNC_ABORT = UNKNOWN;
 #endif
 
 #if LIBCURL_VERSION_NUM >= 0x075100 /* Available since 7.81.0 */

ext/curl/curl_arginfo.h

@@ -1212,6 +1212,9 @@ void _php_setup_easy_copy_handlers(php_curl *ch, php_curl *source)
 	php_curl_copy_fcc_with_option(ch, CURLOPT_PROGRESSDATA, &ch->handlers.progress, &source->handlers.progress);
 	php_curl_copy_fcc_with_option(ch, CURLOPT_XFERINFODATA, &ch->handlers.xferinfo, &source->handlers.xferinfo);
 	php_curl_copy_fcc_with_option(ch, CURLOPT_FNMATCH_DATA, &ch->handlers.fnmatch, &source->handlers.fnmatch);
+#if LIBCURL_VERSION_NUM >= 0x075000 /* Available since 7.80.0 */
+	php_curl_copy_fcc_with_option(ch, CURLOPT_PREREQFUNCTION, &ch->handlers.prereq, &source->handlers.prereq);
+#endif
 #if LIBCURL_VERSION_NUM >= 0x075400 /* Available since 7.84.0 */
 	php_curl_copy_fcc_with_option(ch, CURLOPT_SSH_HOSTKEYDATA, &ch->handlers.sshhostkey, &source->handlers.sshhostkey);
 #endif

ext/curl/interface.c

@@ -0,0 +1,61 @@
+--TEST--
+Curl option CURLOPT_PREREQFUNCTION
+--EXTENSIONS--
+curl
+--SKIPIF--
+<?php
+$curl_version = curl_version();
+if ($curl_version['version_number'] < 0x075000) die("skip: test works only with curl >= 7.80.0");
+?>
+--FILE--
+<?php
+include 'server.inc';
+
+$host = curl_cli_server_start();
+$port = (int) (explode(':', $host))[1];
+
+$ch = curl_init();
+curl_setopt($ch, CURLOPT_URL, $host);
+curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
+//curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4);
+
+var_dump(CURLOPT_PREREQFUNCTION);
+var_dump(CURL_PREREQFUNC_OK);
+var_dump(CURL_PREREQFUNC_ABORT);
+
+curl_setopt($ch, CURLOPT_PREREQFUNCTION, function() use ($port) {
+	var_dump('callback');
+	var_dump(func_num_args());
+	$args = func_get_args();
+	var_dump(get_class($args[0]));
+	var_dump(filter_var($args[1], FILTER_VALIDATE_IP) !== false);
+	var_dump(filter_var($args[2], FILTER_VALIDATE_IP) !== false);
+	var_dump($port === $args[3]);
+	var_dump(is_int($args[4]));
+
+	return CURL_PREREQFUNC_ABORT;
+});
+
+$result = curl_exec($ch);
+
+var_dump($result);
+var_dump(curl_error($ch));
+var_dump(curl_errno($ch));
+
+var_dump('finished');
+?>
+--EXPECT--
+int(20312)
+int(0)
+int(1)
+string(8) "callback"
+int(5)
+string(10) "CurlHandle"
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(false)
+string(41) "operation aborted by pre-request callback"
+int(42)
+string(8) "finished"