Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[PHP 8.4] Curl new options and constants #4069

Merged
merged 9 commits into from
Nov 16, 2024
Merged

[PHP 8.4] Curl new options and constants #4069

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
581bf73
[PHP 8.4] Curl: Add `curl_version` - `features_list` entry
Ayesh Nov 13, 2024
32a4c84
[PHP 8.4] Curl: PHP 8.4 requires libcurl >= 7.61
Ayesh Nov 13, 2024
a8e3078
[PHP 8.4] Curl: `CURLOPT_DNS_USE_GLOBAL_CACHE` no-op
Ayesh Nov 13, 2024
bfcfac6
[PHP 8.4] Curl: Add `CURL_HTTP_VERSION_3(ONLY)` constants
Ayesh Nov 13, 2024
e300f05
[PHP 8.4] Curl: `curl_getinfo` - add `CURLINFO_POSTTRANSFER_TIME_T`
Ayesh Nov 13, 2024
e0a6e5f
[PHP 8.4] Curl: Add `CURLOPT_PREREQFUNCTION` optiona and constants
Ayesh Nov 14, 2024
0ed77f9
[PHP 8.4] Curl: Add `CURLOPT_SERVER_RESPONSE_TIMEOUT`
Ayesh Nov 14, 2024
826c2e6
[PHP 8.4] Curl: Add `CURLOPT_DEBUGFUNCTION`
Ayesh Nov 14, 2024
58e0647
[PHP 8.4] Curl: Add `CURLOPT_TCP_KEEPCNT` option
Ayesh Nov 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions reference/curl/constants.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1374,6 +1374,28 @@
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.curl-http-version-3">
<term>
<constant>CURL_HTTP_VERSION_3</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Available as of PHP 8.4.0 and cURL 7.66.0.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.curl-http-version-3only">
<term>
<constant>CURL_HTTP_VERSION_3ONLY</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Available as of PHP 8.4.0 and cURL 7.88.0.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.curl-http-version-none">
<term>
<constant>CURL_HTTP_VERSION_NONE</constant>
Expand Down Expand Up @@ -2262,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;
Expand Down
12 changes: 12 additions & 0 deletions reference/curl/constants_curl_getinfo.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -776,4 +776,16 @@
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.curlinfo-posttransfer-time-t">
<term>
<constant>CURLINFO_POSTTRANSFER_TIME_T</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Time it took from the start until the last byte is sent, in microseconds.
Available as of PHP 8.4.0 and cURL 8.10.0
</simpara>
</listitem>
</varlistentry>
</variablelist>
235 changes: 235 additions & 0 deletions reference/curl/constants_curl_setopt.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -597,6 +597,7 @@
It is conditionally enabled by default if PHP is built for non-threaded use
(CLI, FCGI, Apache2-Prefork, etc.).
Available as of cURL 7.9.3 and deprecated as of cURL 7.11.1.
As of PHP 8.4, this option no longer has any effect.
</para>
</listitem>
</varlistentry>
Expand Down Expand Up @@ -970,6 +971,8 @@
A timeout in seconds cURL will wait for a response from an FTP server.
This option overrides <constant>CURLOPT_TIMEOUT</constant>.
This option accepts any value that can be cast to a valid <type>int</type>.
This option name is replaced with <constant>CURLOPT_SERVER_RESPONSE_TIMEOUT</constant>,
available as of PHP 8.4.0.
Available as of cURL 7.10.8 and deprecated as of cURL 7.85.0.
</para>
</listitem>
Expand Down Expand Up @@ -3852,6 +3855,8 @@
frequency of these probes can be controlled by the <constant>CURLOPT_TCP_KEEPIDLE</constant>
and <constant>CURLOPT_TCP_KEEPINTVL</constant> options, provided the operating system
supports them. If set to <literal>0</literal> (default) keepalive probes are disabled.
The maximum number of probes can be set with the <constant>CURLOPT_TCP_KEEPCNT</constant>
option.
Available as of cURL 7.25.0.
</para>
</listitem>
Expand Down Expand Up @@ -3886,6 +3891,19 @@
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.curlopt-tcp-keepcnt">
<term>
<constant>CURLOPT_TCP_KEEPCNT</constant>
(<type>int</type>)
</term>
<listitem>
<para>
Sets the maximum number of TCP keep-alive probes.
The default is <literal>9</literal>.
Available as of PHP 8.4.0 and cURL 8.9.0.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.curlopt-tcp-nodelay">
<term>
<constant>CURLOPT_TCP_NODELAY</constant>
Expand Down Expand Up @@ -4427,6 +4445,22 @@
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.curlopt-server-response-timeout">
<term>
<constant>CURLOPT_SERVER_RESPONSE_TIMEOUT</constant>
(<type>int</type>)
</term>
<listitem>
<para>
A timeout in seconds cURL will wait for a response from an
<acronym>FTP</acronym>, <acronym>SFTP</acronym>, <acronym>IMAP</acronym>,
<acronym>SCP</acronym>, <acronym>SMTP</acronym>, or a <acronym>POP3</acronym> server.
This option replaces the existing <constant>CURLOPT_FTP_RESPONSE_TIMEOUT</constant>
option which is deprecated in cURL 7.85.0.
Available as of PHP 8.4.0.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.curlopt-xoauth2-bearer">
<term>
<constant>CURLOPT_XOAUTH2_BEARER</constant>
Expand All @@ -4441,4 +4475,205 @@
</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>
<varlistentry xml:id="constant.curlopt-debugfunction">
<term>
<constant>CURLOPT_DEBUGFUNCTION</constant>
(<type>int</type>)
</term>
<listitem>
<para>
Available as of PHP 8.4.0.
This option requires <constant>CURLOPT_VERBOSE</constant> option enabled.
A <type>callable</type> to replace the standard cURL verbose output.
This callback gets called during various stages of the request with verbose debug information.
The callback should match the following signature:
<methodsynopsis>
<type>void</type><methodname><replaceable>callback</replaceable></methodname>
<methodparam><type>CurlHandle</type><parameter>curlHandle</parameter></methodparam>
<methodparam><type>int</type><parameter>type</parameter></methodparam>
<methodparam><type>string</type><parameter>data</parameter></methodparam>
</methodsynopsis>
<variablelist role="function_parameters">
<varlistentry>
<term><parameter>curlHandle</parameter></term>
<listitem>
<simpara>
The cURL handle.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem>
<simpara>
One of the following constants indicating the type of the <parameter>data</parameter> value:
</simpara>
<variablelist xml:id="constant.curl-debugfunction.constants" role="constant_list">
<varlistentry xml:id="constant.curlinfo-text">
<term>
<constant>CURLINFO_TEXT</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Informational text.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.curlinfo-header-in">
<term>
<constant>CURLINFO_HEADER_IN</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Header (or header-like) data received from the peer.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.curlinfo-header-out-debug">
<term>
<constant linkend="constant.curlinfo-header-out-debug">CURLINFO_HEADER_OUT</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Header (or header-like) data sent to the peer.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.curlinfo-data-in">
<term>
<constant>CURLINFO_DATA_IN</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Unprocessed protocol data received from the peer.
Even if the data is encoded or compressed, it is not provided decoded nor decompressed to this callback.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.curlinfo-data-out">
<term>
<constant>CURLINFO_DATA_OUT</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Protocol data sent to the peer.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.curlinfo-ssl-data-in">
<term>
<constant>CURLINFO_SSL_DATA_IN</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
<acronym>SSL</acronym>/<acronym>TLS</acronym> (binary) data received from the peer.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.curlinfo-ssl-data-out">
<term>
<constant>CURLINFO_SSL_DATA_OUT</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
<acronym>SSL</acronym>/<acronym>TLS</acronym> (binary) data sent to the peer.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<simpara>
Verbose debug data of the type indicate by the <parameter>type</parameter> parameter.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>
</variablelist>
11 changes: 11 additions & 0 deletions reference/curl/functions/curl-getinfo.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,6 +178,11 @@
is set by a previous call to <function>curl_setopt</function>)
</simpara>
</listitem>
<listitem>
<simpara>
"posttransfer_time_us" (Available as of PHP 8.4.0 and cURL 8.10.0)
</simpara>
</listitem>
</itemizedlist>
Note that private data is not included in the associative array and must be retrieved individually with the <constant>CURLINFO_PRIVATE</constant> option.
</para>
Expand All @@ -195,6 +200,12 @@
</row>
</thead>
<tbody>
<row>
<entry>8.4.0</entry>
<entry>
Introduced <constant>CURLINFO_POSTTRANSFER_TIME_T</constant> constant and <literal>posttransfer_time_us</literal> (Curl 8.10.0 or later).
</entry>
</row>
<row>
<entry>8.3.0</entry>
<entry>
Expand Down
7 changes: 7 additions & 0 deletions reference/curl/functions/curl-setopt.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,13 @@
</row>
</thead>
<tbody>
<row>
<entry>8.4.0</entry>
<entry>
<constant>CURLOPT_DNS_USE_GLOBAL_CACHE</constant> no longer has any effect,
and enabling it on thread-safe PHP builds no longer triggers a warning.
</entry>
</row>
&curl.changelog.handle-param;
<row>
<entry>7.3.15, 7.4.3</entry>
Expand Down
Loading