[PHP 8.4] Curl: Add CURLOPT_PREREQFUNCTION optiona and constants

Commit: php/php-src#13255
PHP.Watch: [PHP 8.4: Curl: New `CURLOPT_PREREQFUNCTION` option](https://php.watch/versions/8.4/CURLOPT_PREREQFUNCTION)

Author: Ayesh

reference/curl/constants.xml

@@ -2284,6 +2284,28 @@
     </simpara>
    </listitem>
   </varlistentry>
+  <varlistentry xml:id="constant.curl-prereqfunc-ok">
+   <term>
+    <constant>CURL_PREREQFUNC_OK</constant>
+    (<type>int</type>)
+   </term>
+   <listitem>
+    <simpara>
+     Available as of PHP 8.4.0 and cURL 7.80.0.
+    </simpara>
+   </listitem>
+  </varlistentry>
+  <varlistentry xml:id="constant.curl-prereqfunc-abort">
+   <term>
+    <constant>CURL_PREREQFUNC_ABORT</constant>
+    (<type>int</type>)
+   </term>
+   <listitem>
+    <simpara>
+     Available as of PHP 8.4.0 and cURL 7.80.0.
+    </simpara>
+   </listitem>
+  </varlistentry>
  </variablelist>
  &reference.curl.constants-curl-setopt;
  &reference.curl.constants-curl-share-setopt;

reference/curl/constants_curl_setopt.xml

@@ -4442,4 +4442,78 @@
     </para>
    </listitem>
   </varlistentry>
+  <varlistentry xml:id="constant.curlopt-prereqfunction">
+   <term>
+    <constant>CURLOPT_PREREQFUNCTION</constant>
+    (<type>int</type>)
+   </term>
+   <listitem>
+    <para>
+     A <type>callable</type> with the following signature that gets called after the
+     connection is established, but before the request payload (for example, the
+     GET/POST/DELETE request of an HTTP connection) is sent, and can be used to abort
+     or allow the connection depending on the source and destination IP address and
+     port numbers:
+     <methodsynopsis>
+      <type>int</type><methodname><replaceable>callback</replaceable></methodname>
+      <methodparam><type>CurlHandle</type><parameter>curlHandle</parameter></methodparam>
+      <methodparam><type>string</type><parameter>destination_ip</parameter></methodparam>
+      <methodparam><type>string</type><parameter>local_ip</parameter></methodparam>
+      <methodparam><type>int</type><parameter>destination_port</parameter></methodparam>
+      <methodparam><type>int</type><parameter>local_port</parameter></methodparam>
+     </methodsynopsis>
+     <variablelist role="function_parameters">
+      <varlistentry>
+       <term><parameter>curlHandle</parameter></term>
+       <listitem>
+        <simpara>
+         The cURL handle.
+        </simpara>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term><parameter>destination_ip</parameter></term>
+       <listitem>
+        <simpara>
+         The primary IP of the remote server established with this connection.
+         For <acronym>FTP</acronym>, this is the IP for the control connection.
+         IPv6 addresses are represented without surrounding brackets.
+        </simpara>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term><parameter>local_ip</parameter></term>
+       <listitem>
+        <simpara>
+         The originating IP for this connection.
+         IPv6 addresses are represented without surrounding brackets.
+        </simpara>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term><parameter>destination_port</parameter></term>
+       <listitem>
+        <simpara>
+         The primary port number on the remote server established with this connection.
+         For <acronym>FTP</acronym>, this is the port for the control connection.
+         This can be a <acronym>TCP</acronym> or a <acronym>UDP</acronym> port number depending on the protocol.
+        </simpara>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term><parameter>local_port</parameter></term>
+       <listitem>
+        <simpara>
+         The originating port number for this connection.
+         This can be a <acronym>TCP</acronym> or a <acronym>UDP</acronym> port number depending on the protocol.
+        </simpara>
+       </listitem>
+      </varlistentry>
+     </variablelist>
+     Return <constant>CURL_PREREQFUNC_OK</constant> to allow the request, or
+     <constant>CURL_PREREQFUNC_ABORT</constant> to abort the transfer.
+     Available as of PHP 8.4.0 and cURL 7.80.0.
+    </para>
+   </listitem>
+  </varlistentry>
  </variablelist>