ext/curl: add socket callback options bridging to ext/sockets

Expose libcurl's CURLOPT_SOCKOPTFUNCTION, CURLOPT_OPENSOCKETFUNCTION and
CURLOPT_CLOSESOCKETFUNCTION, letting userland hook into socket creation,
configuration and teardown. These are useful for application security, in
particular SSRF protection (validating the resolved address before connecting)
and low-level socket hardening.

Following the existing curl_write_header / curl_prereqfunction bridge model, the
callbacks exchange ext/sockets Socket objects so they are fully usable in pure
PHP (socket_create/socket_bind, socket_set_option, socket_close):

  - sockopt:     fn(CurlHandle $ch, Socket $socket, int $purpose): int
                 returns CURL_SOCKOPT_OK / _ERROR / _ALREADY_CONNECTED
  - opensocket:  fn(CurlHandle $ch, int $purpose, array $address): Socket|false
                 $address = [family, socktype, protocol, ip, port];
                 returning false aborts the connection (CURL_SOCKET_BAD)
  - closesocket: fn(CurlHandle $ch, Socket $socket): void

This is achieved through the C API exported by ext/sockets (socket_ce, the
php_socket struct and socket_import_file_descriptor()), so ext/curl now depends
on ext/sockets. The whole feature is guarded by HAVE_SOCKETS; without the
sockets extension curl still builds, just without these options.

Notable details:
  - Descriptors owned by libcurl are detached (bsd_socket = -1) before the
    temporary Socket object is released, to avoid a double close.
  - The close-socket callback is disabled before curl_easy_cleanup() so libcurl
    closes pooled sockets natively rather than calling into PHP during handle
    destruction.
  - Setting an option to null restores libcurl's native default.

New constants: CURLOPT_SOCKOPTFUNCTION, CURLOPT_OPENSOCKETFUNCTION,
CURLOPT_CLOSESOCKETFUNCTION, CURL_SOCKOPT_OK, CURL_SOCKOPT_ERROR,
CURL_SOCKOPT_ALREADY_CONNECTED, CURLSOCKTYPE_IPCXN, CURLSOCKTYPE_ACCEPT.

Author: xavierleune

NEWS

@@ -25,6 +25,11 @@ PHP                                                                        NEWS
 - BCMath:
   . Added NUL-byte validation to BCMath functions. (jorgsowa)
 
+- Curl:
+  . Added CURLOPT_SOCKOPTFUNCTION, CURLOPT_OPENSOCKETFUNCTION and
+    CURLOPT_CLOSESOCKETFUNCTION options, bridging libcurl's socket callbacks to
+    ext/sockets Socket objects (requires the sockets extension).
+
 - Date:
   . Update timelib to 2022.16. (Derick)
 

UPGRADING

@@ -171,6 +171,16 @@ PHP 8.6 UPGRADE NOTES
   . It is now possible to define the `__debugInfo()` magic method on enums.
     RFC: https://wiki.php.net/rfc/debugable-enums
 
+- Curl:
+  . Added the CURLOPT_SOCKOPTFUNCTION, CURLOPT_OPENSOCKETFUNCTION and
+    CURLOPT_CLOSESOCKETFUNCTION options, which let userland hook into libcurl's
+    socket creation, configuration and teardown. The callbacks exchange
+    ext/sockets Socket objects, e.g. to validate the resolved address before
+    connecting (SSRF protection) or to set low-level socket options. These
+    options require the sockets extension; the new CURL_SOCKOPT_OK,
+    CURL_SOCKOPT_ERROR, CURL_SOCKOPT_ALREADY_CONNECTED, CURLSOCKTYPE_IPCXN and
+    CURLSOCKTYPE_ACCEPT constants are defined alongside them.
+
 - Fileinfo:
   . finfo_file() now works with remote streams.
 

ext/curl/config.m4

@@ -75,6 +75,10 @@ if test "$PHP_CURL" != "no"; then
   PHP_NEW_EXTENSION([curl],
     [interface.c multi.c share.c curl_file.c],
     [$ext_shared])
+  dnl The CURLOPT_SOCKOPT/OPENSOCKET/CLOSESOCKETFUNCTION callbacks bridge to
+  dnl ext/sockets Socket objects (guarded by HAVE_SOCKETS). The dependency is
+  dnl optional: without sockets, curl still builds, just without those options.
+  PHP_ADD_EXTENSION_DEP(curl, sockets, true)
   PHP_INSTALL_HEADERS([ext/curl], [php_curl.h])
   PHP_SUBST([CURL_SHARED_LIBADD])
 fi

ext/curl/config.w32

@@ -25,6 +25,10 @@ if (PHP_CURL != "no") {
 			WARNING("zstd in curl not enabled; library not found");
 		}
 		EXTENSION("curl", "interface.c multi.c share.c curl_file.c");
+		// The socket callbacks (CURLOPT_SOCKOPT/OPENSOCKET/CLOSESOCKETFUNCTION)
+		// bridge to ext/sockets Socket objects, guarded by HAVE_SOCKETS. Optional:
+		// without sockets, curl still builds, just without those options.
+		ADD_EXTENSION_DEP('curl', 'sockets', true);
 		AC_DEFINE('HAVE_CURL', 1, "Define to 1 if the PHP extension 'curl' is available.");
 		ADD_FLAG("CFLAGS_CURL", "/D PHP_CURL_EXPORTS=1");
 		if (curl_location.match(/libcurl_a\.lib$/)) {

ext/curl/curl.stub.php

@@ -2327,6 +2327,63 @@
  */
 const CURL_FNMATCHFUNC_NOMATCH = UNKNOWN;
 
+#ifdef HAVE_SOCKETS
+/**
+ * Used with CURLOPT_SOCKOPTFUNCTION, which receives a Socket wrapping the
+ * descriptor libcurl just created and must return one of the CURL_SOCKOPT_*
+ * constants below.
+ * @var int
+ * @cvalue CURLOPT_SOCKOPTFUNCTION
+ */
+const CURLOPT_SOCKOPTFUNCTION = UNKNOWN;
+/**
+ * Used with CURLOPT_OPENSOCKETFUNCTION, which receives the resolved address and
+ * must return a Socket to use for the connection, or false to abort it.
+ * @var int
+ * @cvalue CURLOPT_OPENSOCKETFUNCTION
+ */
+const CURLOPT_OPENSOCKETFUNCTION = UNKNOWN;
+/**
+ * Used with CURLOPT_CLOSESOCKETFUNCTION, which is notified when libcurl is done
+ * with a socket created by the open-socket callback.
+ * @var int
+ * @cvalue CURLOPT_CLOSESOCKETFUNCTION
+ */
+const CURLOPT_CLOSESOCKETFUNCTION = UNKNOWN;
+/**
+ * Return value for the CURLOPT_SOCKOPTFUNCTION callback: proceed normally.
+ * @var int
+ * @cvalue CURL_SOCKOPT_OK
+ */
+const CURL_SOCKOPT_OK = UNKNOWN;
+/**
+ * Return value for the CURLOPT_SOCKOPTFUNCTION callback: abort the connection.
+ * @var int
+ * @cvalue CURL_SOCKOPT_ERROR
+ */
+const CURL_SOCKOPT_ERROR = UNKNOWN;
+/**
+ * Return value for the CURLOPT_SOCKOPTFUNCTION callback: the socket is already
+ * connected, so libcurl should skip its own connect step.
+ * @var int
+ * @cvalue CURL_SOCKOPT_ALREADY_CONNECTED
+ */
+const CURL_SOCKOPT_ALREADY_CONNECTED = UNKNOWN;
+/**
+ * Purpose passed to the socket callbacks: a socket for a regular IP connection.
+ * @var int
+ * @cvalue CURLSOCKTYPE_IPCXN
+ */
+const CURLSOCKTYPE_IPCXN = UNKNOWN;
+/**
+ * Purpose passed to the socket callbacks: a socket created from accept() (e.g.
+ * active FTP).
+ * @var int
+ * @cvalue CURLSOCKTYPE_ACCEPT
+ */
+const CURLSOCKTYPE_ACCEPT = UNKNOWN;
+#endif
+
 /* Available since 7.21.2 */
 /**
  * @var int

ext/curl/curl_arginfo.h

@@ -84,6 +84,11 @@ typedef struct {
 #if LIBCURL_VERSION_NUM >= 0x075400 /* Available since 7.84.0 */
 	zend_fcall_info_cache sshhostkey;
 #endif
+#ifdef HAVE_SOCKETS
+	zend_fcall_info_cache sockopt;
+	zend_fcall_info_cache opensocket;
+	zend_fcall_info_cache closesocket;
+#endif
 } php_curl_handlers;
 
 struct _php_curl_error  {