ext/curl: Add CURLOPT_DEBUGFUNCTION

[Ayesh]

This adds support for CURLOPT_DEBUGFUNCTION¹ Curl option to set a custom callback that gets called with debug information during the lifetime of a Curl request.

The callback gets called with the CurlHandle object, an integer containing the type of the debug message, and a string containing the debug message. The callback may get called multiple times with the same message type during a request.

PHP already uses CURLOPT_DEBUGFUNCTION functionality to internally to expose a Curl option named CURLINFO_HEADER_OUT.

However,CURLINFO_HEADER_OUT is not a "real" Curl option supported by libcurl. Back in 2016, CURLINFO_HEADER_OUT was added as a Curl option by using the debug-callback feature. Git history does not run that back to show why CURLINFO_HEADER_OUT was added as a Curl option, and why the other debug types (such as CURLINFO_HEADER_IN_ were not added as Curl options, but this seems to be a historical artifact when we added features without trying to be close to libcurl options.

This approach has a few issues:

1. CURLINFO_HEADER_OUT is not an actual Curl option supported by upstream libcurl.

2. All of the Curl options have CURLOPT_ prefix, and CURLINFO_HEADER_OUT is the only Curl "option" that uses the CURLINFO prefix. This exception is, however, noted² in docs.

3. When CURLINFO_HEADER_OUT is set, the CURLOPT_VERBOSE is also implicitly set. This was reported³ to bugs.php.net, but the bug is marked as wontfix.

This commit adds support for CURLOPT_DEBUGFUNCTION. It extends the existing curl_debug callback to store the header-in information if it encounters a debug message with CURLINFO_HEADER_OUT. In all cases, if a callable is set, it gets called.

CURLOPT_DEBUGFUNCTION intends to replace CURLINFO_HEADER_OUT Curl option as a versatile alternative that can also be used to extract other debug information such as SSL data, text information messages, incoming headers, as well as headers sent out (which CURLINFO_HEADER_OUT makes available).

The callables are allowed to throw exceptions, but the return values are ignored.

CURLOPT_DEBUGFUNCTION requires CURLOPT_VERBOSE enabled, and setting CURLOPT_DEBUGFUNCTION does not implicitly enable CURLOPT_VERBOSE.

If the CURLOPT_DEBUGFUNCTION option is set, setting CURLINFO_HEADER_OUT throws a ValueError exception. Setting CURLOPT_DEBUGFUNCTION after enabling CURLINFO_HEADER_OUT is allowed. Technically, it is possible for both functionality (calling user-provided callback and storing header-out data) is possible, setting CURLINFO_HEADER_OUT is not allowed to encourage the use of CURLOPT_DEBUGFUNCTION function.

This commit also adds the rest of the CURLINFO_ constants used as the type integer value in CURLOPT_DEBUGFUNCTION callback.

---

Footnotes

1. cur.se - CURLOPT_DEBUGFUNCTION ↩

2. curl_setopt doc mentioning CURLINFO_ prefix is intentional ↩

3. bugs.php.net - CURLOPT_VERBOSE does not work with CURLINFO_HEADER_OUT ↩