Skip to content

Commit 1f48e68

Browse files
AyeshAyesh
committed
ext/curl: Add CURLOPT_DEBUGFUNCTION
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 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[^2] in docs. 3. When `CURLINFO_HEADER_OUT` is set, the `CURLOPT_VERBOSE` is also implicitly set. This was reported[^3] 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]: [curl_setopt doc mentioning `CURLINFO_` prefix is intentional](https://www.php.net/manual/en/function.curl-setopt.php#:~:text=prefix%20is%20intentional) [^3]: [bugs.php.net - `CURLOPT_VERBOSE` does not work with `CURLINFO_HEADER_OUT`](https://bugs.php.net/bug.php?id=65348)
1 parent fc01e2e commit 1f48e68

8 files changed

+336
-10
lines changed

‎NEWS

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ PHP NEWS
77
. Fixed bug GH-15644 (Asymmetric visibility doesn't work with hooks). (ilutov)
88
. Implemented lazy objects RFC. (Arnaud)
99

10+
- Curl:
11+
. Added CURLOPT_DEBUGFUNCTION as a Curl option. (Ayesh Karunaratne)
12+
1013
- DOM:
1114
. Fixed bug GH-13988 (Storing DOMElement consume 4 times more memory in
1215
PHP 8.1 than in PHP 8.0). (nielsdos)

‎UPGRADING

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -292,6 +292,13 @@ PHP 8.4 UPGRADE NOTES
292292
supported (true) or not (false).
293293
. Added CURL_HTTP_VERSION_3 and CURL_HTTP_VERSION_3ONLY constants (available
294294
since libcurl 7.66 and 7.88) as available options for CURLOPT_HTTP_VERSION.
295+
. Added CURLOPT_DEBUGFUNCTION support. This Curl option accepts a callable
296+
that gets called during the request lifetime with the CurlHandle object,
297+
an integer containing the debug message type, and a string containing the
298+
debug message. The debug message type is one of CURLINFO_TEXT, CURLINFO_HEADER_IN,
299+
CURLINFO_HEADER_OUT, CURLINFO_DATA_IN, CURLINFO_DATA_OUT, CURLINFO_SSL_DATA_OUT,
300+
CURLINFO_SSL_DATA_IN constants. Once this option is set, CURLINFO_HEADER_OUT
301+
must not be set because it uses the same libcurl functionality.
295302

296303
- Date:
297304
. Added static methods
@@ -996,6 +1003,13 @@ PHP 8.4 UPGRADE NOTES
9961003
. CURL_HTTP_VERSION_3.
9971004
. CURL_HTTP_VERSION_3ONLY.
9981005
. CURL_TCP_KEEPCNT
1006+
. CURLOPT_DEBUGFUNCTION.
1007+
. CURLINFO_TEXT.
1008+
. CURLINFO_HEADER_IN.
1009+
. CURLINFO_DATA_IN.
1010+
. CURLINFO_DATA_OUT.
1011+
. CURLINFO_SSL_DATA_OUT.
1012+
. CURLINFO_SSL_DATA_IN.
9991013

10001014
- Intl:
10011015
. The IntlDateFormatter class exposes now the new PATTERN constant

‎ext/curl/curl.stub.php

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -485,6 +485,48 @@
485485
*/
486486
const CURLOPT_XFERINFOFUNCTION = UNKNOWN;
487487

488+
/**
489+
* @var int
490+
* @cvalue CURLOPT_DEBUGFUNCTION
491+
*/
492+
const CURLOPT_DEBUGFUNCTION = UNKNOWN;
493+
494+
/**
495+
* @var int
496+
* @cvalue CURLINFO_TEXT
497+
*/
498+
const CURLINFO_TEXT = UNKNOWN;
499+
500+
/**
501+
* @var int
502+
* @cvalue CURLINFO_HEADER_IN
503+
*/
504+
const CURLINFO_HEADER_IN = UNKNOWN;
505+
506+
/**
507+
* @var int
508+
* @cvalue CURLINFO_DATA_IN
509+
*/
510+
const CURLINFO_DATA_IN = UNKNOWN;
511+
512+
/**
513+
* @var int
514+
* @cvalue CURLINFO_DATA_OUT
515+
*/
516+
const CURLINFO_DATA_OUT = UNKNOWN;
517+
518+
/**
519+
* @var int
520+
* @cvalue CURLINFO_SSL_DATA_OUT
521+
*/
522+
const CURLINFO_SSL_DATA_OUT = UNKNOWN;
523+
524+
/**
525+
* @var int
526+
* @cvalue CURLINFO_SSL_DATA_IN
527+
*/
528+
const CURLINFO_SSL_DATA_IN = UNKNOWN;
529+
488530
/* */
489531
/**
490532
* @var int

‎ext/curl/curl_arginfo.h

Lines changed: 8 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎ext/curl/curl_private.h

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@ typedef struct {
6868
zend_fcall_info_cache progress;
6969
zend_fcall_info_cache xferinfo;
7070
zend_fcall_info_cache fnmatch;
71+
zend_fcall_info_cache debug;
7172
#if LIBCURL_VERSION_NUM >= 0x075000 /* Available since 7.80.0 */
7273
zend_fcall_info_cache prereq;
7374
#endif

‎ext/curl/interface.c

Lines changed: 57 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -504,6 +504,10 @@ static HashTable *curl_get_gc(zend_object *object, zval **table, int *n)
504504
zend_get_gc_buffer_add_fcc(gc_buffer, &curl->handlers.fnmatch);
505505
}
506506

507+
if (ZEND_FCC_INITIALIZED(curl->handlers.debug)) {
508+
zend_get_gc_buffer_add_fcc(gc_buffer, &curl->handlers.debug);
509+
}
510+
507511
#if LIBCURL_VERSION_NUM >= 0x075000 /* Available since 7.80.0 */
508512
if (ZEND_FCC_INITIALIZED(curl->handlers.prereq)) {
509513
zend_get_gc_buffer_add_fcc(gc_buffer, &curl->handlers.prereq);
@@ -915,18 +919,46 @@ static size_t curl_write_header(char *data, size_t size, size_t nmemb, void *ctx
915919
}
916920
/* }}} */
917921

918-
static int curl_debug(CURL *cp, curl_infotype type, char *buf, size_t buf_len, void *ctx) /* {{{ */
922+
static int curl_debug(CURL *handle, curl_infotype type, char *data, size_t size, void *clientp) /* {{{ */
919923
{
920-
php_curl *ch = (php_curl *)ctx;
924+
php_curl *ch = (php_curl *)clientp;
921925

922-
if (type == CURLINFO_HEADER_OUT) {
923-
if (ch->header.str) {
924-
zend_string_release_ex(ch->header.str, 0);
925-
}
926-
ch->header.str = zend_string_init(buf, buf_len, 0);
927-
}
926+
#if PHP_CURL_DEBUG
927+
fprintf(stderr, "curl_debug() called\n");
928+
fprintf(stderr, "type = %d, data = %s\n", type, data);
929+
#endif
930+
931+
// Implicitly store the headers for compatibility with CURLINFO_HEADER_OUT
932+
// used as a Curl option. Previously, setting CURLINFO_HEADER_OUT set curl_debug
933+
// as the CURLOPT_DEBUGFUNCTION and storing the debug data when type is set to
934+
// CURLINFO_HEADER_OUT. For backward compatibility, we now store the headers
935+
// but also call the user-callback function if available.
936+
if (type == CURLINFO_HEADER_OUT) {
937+
if (ch->header.str) {
938+
zend_string_release_ex(ch->header.str, 0);
939+
}
940+
ch->header.str = zend_string_init(data, size, 0);
941+
}
942+
943+
if (!ZEND_FCC_INITIALIZED(ch->handlers.debug)) {
944+
return 0;
945+
}
928946

929-
return 0;
947+
zval args[3];
948+
949+
GC_ADDREF(&ch->std);
950+
ZVAL_OBJ(&args[0], &ch->std);
951+
ZVAL_LONG(&args[1], type);
952+
ZVAL_STRINGL(&args[2], data, size);
953+
954+
ch->in_callback = true;
955+
zend_call_known_fcc(&ch->handlers.debug, NULL, /* param_count */ 3, args, /* named_params */ NULL);
956+
ch->in_callback = false;
957+
958+
zval_ptr_dtor(&args[0]);
959+
zval_ptr_dtor(&args[1]);
960+
961+
return 0;
930962
}
931963
/* }}} */
932964

@@ -1096,6 +1128,7 @@ void init_curl_handle(php_curl *ch)
10961128
ch->handlers.progress = empty_fcall_info_cache;
10971129
ch->handlers.xferinfo = empty_fcall_info_cache;
10981130
ch->handlers.fnmatch = empty_fcall_info_cache;
1131+
ch->handlers.debug = empty_fcall_info_cache;
10991132
#if LIBCURL_VERSION_NUM >= 0x075000 /* Available since 7.80.0 */
11001133
ch->handlers.prereq = empty_fcall_info_cache;
11011134
#endif
@@ -1272,6 +1305,7 @@ void _php_setup_easy_copy_handlers(php_curl *ch, php_curl *source)
12721305
php_curl_copy_fcc_with_option(ch, CURLOPT_PROGRESSDATA, &ch->handlers.progress, &source->handlers.progress);
12731306
php_curl_copy_fcc_with_option(ch, CURLOPT_XFERINFODATA, &ch->handlers.xferinfo, &source->handlers.xferinfo);
12741307
php_curl_copy_fcc_with_option(ch, CURLOPT_FNMATCH_DATA, &ch->handlers.fnmatch, &source->handlers.fnmatch);
1308+
php_curl_copy_fcc_with_option(ch, CURLOPT_DEBUGDATA, &ch->handlers.debug, &source->handlers.debug);
12751309
#if LIBCURL_VERSION_NUM >= 0x075000 /* Available since 7.80.0 */
12761310
php_curl_copy_fcc_with_option(ch, CURLOPT_PREREQDATA, &ch->handlers.prereq, &source->handlers.prereq);
12771311
#endif
@@ -1635,6 +1669,8 @@ static zend_result _php_curl_setopt(php_curl *ch, zend_long option, zval *zvalue
16351669
HANDLE_CURL_OPTION_CALLABLE(ch, CURLOPT_PROGRESS, handlers.progress, curl_progress);
16361670
HANDLE_CURL_OPTION_CALLABLE(ch, CURLOPT_XFERINFO, handlers.xferinfo, curl_xferinfo);
16371671
HANDLE_CURL_OPTION_CALLABLE(ch, CURLOPT_FNMATCH_, handlers.fnmatch, curl_fnmatch);
1672+
HANDLE_CURL_OPTION_CALLABLE(ch, CURLOPT_DEBUG, handlers.debug, curl_debug);
1673+
16381674
#if LIBCURL_VERSION_NUM >= 0x075000 /* Available since 7.80.0 */
16391675
HANDLE_CURL_OPTION_CALLABLE(ch, CURLOPT_PREREQ, handlers.prereq, curl_prereqfunction);
16401676
#endif
@@ -2225,6 +2261,11 @@ static zend_result _php_curl_setopt(php_curl *ch, zend_long option, zval *zvalue
22252261
}
22262262

22272263
case CURLINFO_HEADER_OUT:
2264+
if (ZEND_FCC_INITIALIZED(ch->handlers.debug)) {
2265+
zend_value_error("CURLINFO_HEADER_OUT option must not be set when the CURLOPT_DEBUGFUNCTION option is set");
2266+
return FAILURE;
2267+
}
2268+
22282269
if (zend_is_true(zvalue)) {
22292270
curl_easy_setopt(ch->cp, CURLOPT_DEBUGFUNCTION, curl_debug);
22302271
curl_easy_setopt(ch->cp, CURLOPT_DEBUGDATA, (void *)ch);
@@ -2804,6 +2845,9 @@ static void curl_free_obj(zend_object *object)
28042845
if (ZEND_FCC_INITIALIZED(ch->handlers.fnmatch)) {
28052846
zend_fcc_dtor(&ch->handlers.fnmatch);
28062847
}
2848+
if (ZEND_FCC_INITIALIZED(ch->handlers.debug)) {
2849+
zend_fcc_dtor(&ch->handlers.debug);
2850+
}
28072851
#if LIBCURL_VERSION_NUM >= 0x075000 /* Available since 7.80.0 */
28082852
if (ZEND_FCC_INITIALIZED(ch->handlers.prereq)) {
28092853
zend_fcc_dtor(&ch->handlers.prereq);
@@ -2887,6 +2931,10 @@ static void _php_curl_reset_handlers(php_curl *ch)
28872931
if (ZEND_FCC_INITIALIZED(ch->handlers.fnmatch)) {
28882932
zend_fcc_dtor(&ch->handlers.fnmatch);
28892933
}
2934+
2935+
if (ZEND_FCC_INITIALIZED(ch->handlers.debug)) {
2936+
zend_fcc_dtor(&ch->handlers.debug);
2937+
}
28902938
#if LIBCURL_VERSION_NUM >= 0x075000 /* Available since 7.80.0 */
28912939
if (ZEND_FCC_INITIALIZED(ch->handlers.prereq)) {
28922940
zend_fcc_dtor(&ch->handlers.prereq);

‎ext/curl/sync-constants.php

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
'CURLOPT_PROGRESSDATA',
1919
'CURLOPT_XFERINFODATA',
2020
'CURLOPT_PREREQDATA',
21+
'CURLOPT_DEBUGDATA',
2122
];
2223

2324
const IGNORED_PHP_CONSTANTS = [

0 commit comments

Comments
 (0)