Update curl_getinfo() return types

[FeBe95]

Summary

This PR adds new return types for curl_getinfo() for new CURLINFO_* constants that were added in recent PHP 8.x versions. It also corrects the return types of some existing options that were incorrect.

I have also added the appropriate tests for all new constants and adjusted the existing ones.

Details

Note

Theoretically, every single option could potentially return false if the loaded curl library doesn't support it.¹ However, as this is unlikely to happen in production, I decided to keep things mostly as they are, to avoid breaking any existing setups. I only added false to the return type if the option is only available in newer cURL versions (>=8.0.0 – March 2023²), or if there is another specific reason for doing so.

Changed Types

• 🛠️ CURLINFO_REDIRECT_URL: Returns a string if CURLOPT_FOLLOWLOCATION is disabled, false otherwise.
• 🛠️ CURLINFO_SIZE_UPLOAD, CURLINFO_SIZE_DOWNLOAD, CURLINFO_SPEED_DOWNLOAD, CURLINFO_SPEED_UPLOAD: Returns an integer.
• 🛠️ CURLINFO_PRIVATE: PHP treats this like a classic variable.³ I tested null|bool|int|float|string|array|object|resource.⁴
• 🆕 CURLINFO_HTTP_CODE: (Legacy) alias of CURLINFO_RESPONSE_CODE as of PHP 5.5 and cURL 7.10.8.
• 🛠️ CURLINFO_SSL_ENGINES, CURLINFO_COOKIELIST: Returns a list (instead of an indexed array).
• 🛠️ CURLINFO_CERTINFO: Returns a list of associative arrays (instead of an indexed array).
• 🛠️ CURLINFO_RTSP_SESSION_ID: Returns a string.⁵⁶ Returns false if no ID was set or if the protocol is not rtsp://.
• 🛠️ CURLINFO_PROTOCOL: Returns an integer, a CURLPROTO_* constant value: $\{{-1}, 2^0, 2^1, 2^2, \dots, 2^{27}, 2^{28}\}$.

Added Types (PHP 8.2)

• 🆕 CURLINFO_EFFECTIVE_METHOD: Returns a string.
• 🆕 CURLINFO_PROXY_ERROR: Returns an integer, a CURLPX_* constant value: $\{0, 1, \dots, 32, 33\}$.
• 🆕 CURLINFO_REFERER: Returns a string if CURLOPT_FOLLOWLOCATION and CURLOPT_AUTOREFERER are enabled, false otherwise.
• 🆕 CURLINFO_RETRY_AFTER: Returns an integer (number of seconds, even if the Retry-After header is a timestamp string).

Added Types (PHP 8.3)

• 🆕 CURLINFO_CAINFO: Returns a string for the CA file path or false if it is not set.
• 🆕 CURLINFO_CAPATH: Returns a string for the CA directory or false if it is not set.

Added Types (PHP 8.4)

• 🆕 CURLINFO_POSTTRANSFER_TIME_T: Returns an integer. Since cURL v8.10.0, false otherwise.

Note

PHP 8.4 introduced some more unrelated CURLINFO_* constants, such as CURLINFO_DATA_IN and CURLINFO_SSL_DATA_IN. These constants are not intended for use with curl_getinfo(). Instead, they are used in the callback of CURLOPT_DEBUGFUNCTION.

Added Types (PHP 8.5)

• 🆕 CURLINFO_QUEUE_TIME_T: Returns an integer. Since cURL v8.6.0, false otherwise.
• 🆕 CURLINFO_USED_PROXY: Returns an integer, resprenting no/yes: $\{0, 1\}$. Since cURL v8.7.0, false otherwise.
• 🆕 CURLINFO_HTTPAUTH_USED: Returns an integer (a CURLAUTH_* constant value). Since cURL v8.12.0, false otherwise.
• 🆕 CURLINFO_PROXYAUTH_USED: Returns an integer (a CURLAUTH_* constant value). Since cURL v8.12.0, false otherwise.
• 🆕 CURLINFO_CONN_ID: Returns an integer. Since cURL v8.2.0, false otherwise.

Sources

PHP Manual:

• https://www.php.net/manual/en/curl.constants.php#constant.curl-getinfo.constants
• https://www.php.net/manual/en/function.curl-getinfo.php

cURL Documentation

• https://curl.se/libcurl/c/curl_easy_getinfo.html
• https://curl.se/libcurl/c/symbols-in-versions.html

PHP.Watch

• https://php.watch/codex?search=CURLINFO_

GitHub Repos

• curl/curl:
  • /include/curl/curl.h#L2904-L3000
  • /lib/vtls/openssl.c#L390-L624
• php/php-src:
  • /ext/curl/interface.c#L2476-L2638
  • /ext/curl/interface.c#L2641-L2732
• JetBrains/phpstorm-stubs:
  • /blob/master/curl/curl_d.php

Footnotes

1. There are RETURN FALSE fallbacks for every data type: php/php-src/ext/curl/interface.c#L2641-L2732 ↩

2. cURL 8.0.0 release: https://curl.se/ch/8.0.0.html ↩

3. PHP uses the general zval container data type for the private data: php/php-src/ext/curl/interface.c#L1966-L1967 ↩

4. PHP Debugging Script (PHP 8.2.12 and cURL 8.4.0): https://gist.github.com/FeBe95/8a947dd392c1d1693cfc72eb9501d2c7 ↩

5. IETF RTSP RFC, section "3.4 Session Identifiers": https://www.ietf.org/rfc/rfc2326.txt ↩

6. The value of CURLINFO_RTSP_SESSION_ID is CURLINFO_STRING + 36: curl/curl/include/curl/curl.h#L2962 ↩