mirror of
https://github.com/php/php-src.git
synced 2025-08-15 21:48:51 +02:00
ba748e7bb5
This adds support for `CURLOPT_DEBUGFUNCTION`[^1] 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 2006, `CURLINFO_HEADER_OUT` was added[^2] 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[^3] in docs.
3. When `CURLINFO_HEADER_OUT` is set, the `CURLOPT_VERBOSE` is also implicitly
set. This was reported[^4] 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.
---
[^1]: [cur.se - CURLOPT_DEBUGFUNCTION](https://curl.se/libcurl/c/CURLOPT_DEBUGFUNCTION.html)
[^2]: [`5f25d80`](
|
||
|---|---|---|
| .. | ||
| bcmath | ||
| bz2 | ||
| calendar | ||
| com_dotnet | ||
| ctype | ||
| curl | ||
| date | ||
| dba | ||
| dl_test | ||
| dom | ||
| enchant | ||
| exif | ||
| ffi | ||
| fileinfo | ||
| filter | ||
| ftp | ||
| gd | ||
| gettext | ||
| gmp | ||
| hash | ||
| iconv | ||
| intl | ||
| json | ||
| ldap | ||
| libxml | ||
| mbstring | ||
| mysqli | ||
| mysqlnd | ||
| odbc | ||
| opcache | ||
| openssl | ||
| pcntl | ||
| pcre | ||
| pdo | ||
| pdo_dblib | ||
| pdo_firebird | ||
| pdo_mysql | ||
| pdo_odbc | ||
| pdo_pgsql | ||
| pdo_sqlite | ||
| pgsql | ||
| phar | ||
| posix | ||
| random | ||
| readline | ||
| reflection | ||
| session | ||
| shmop | ||
| simplexml | ||
| skeleton | ||
| snmp | ||
| soap | ||
| sockets | ||
| sodium | ||
| spl | ||
| sqlite3 | ||
| standard | ||
| sysvmsg | ||
| sysvsem | ||
| sysvshm | ||
| tidy | ||
| tokenizer | ||
| xml | ||
| xmlreader | ||
| xmlwriter | ||
| xsl | ||
| zend_test | ||
| zip | ||
| zlib | ||
| ext_skel.php | ||