PHP 8.4: Curl: Новая опция CURLOPT_DEBUGFUNCTION
CURLOPT_DEBUGFUNCTION для установки пользовательской функции обратного вызова, вызываемой вместо стандартной функции вывода сообщений.Когда выполняется запрос Curl, настройка подробного вывода выводит дополнительную отладочную информацию в течение всего времени выполнения запроса, что может быть удобно для отладки неудачных запросов Curl или для ведения лога запросов Curl.
Curl также предоставляет опцию CURLOPT_DEBUGFUNCTION для установки пользовательской функции обратного вызова, вызываемой вместо стандартной функции вывода сообщений. Когда приложению требуется больше контроля над обработкой подробной отладочной информации, эта опция может быть полезна.
Расширение PHP 8.4 Curl предоставляет эту опцию libcurl как опцию CURLOPT_DEBUGFUNCTION (для curl_setopt), принимающую значение PHP callable.
Обратный вызов вызывается несколько раз во время запроса Curl, и обратный вызов может решить, что делать с этой информацией.
Новые константы
В рамках этой функции добавлены следующие новые константы PHP:
CURLOPT_DEBUGFUNCTION:intприсвоено20094: Опцияcurl_setopt.
Типы отладочной информации
callable вызывается со значением int одной из следующих констант, указывающей, какие данные передаются в качестве следующего параметра.
| Константа | Указание |
|---|---|
CURLINFO_TEXT | Информационный текст |
CURLINFO_HEADER_IN | Данные заголовка (или данные, похожие на заголовок), полученные от пира |
CURLINFO_HEADER_OUT | Данные заголовка (или данные, похожие на заголовок), отправленные пиру |
CURLINFO_DATA_IN | Необработанные данные протокола , полученные от пира. Даже если данные закодированы или сжаты, они не предоставляются этому обратному вызову ни в декодированном, ни в декомпрессированном виде |
CURLINFO_DATA_OUT | Данные протокола, отправленные пиру |
CURLINFO_SSL_DATA_IN | SSL/TLS данные (бинарные), полученные от пира |
CURLINFO_SSL_DATA_OUT | SSL/TLS данные (бинарные), отправленные пиру |
Обратите внимание, что константа CURLINFO_HEADER_OUT уже существовала в предыдущих версиях PHP. Более подробную информацию смотрите в разделе Использование с CURLINFO_HEADER_OUT.
Опция CURLOPT_DEBUGFUNCTION
Опция Curl CURLOPT_DEBUGFUNCTION принимает вызываемое значение, вызываемое каждый раз, когда Curl выдаёт отладочную информацию. Чтобы обратный вызов был вызван, опция CURLOPT_VERBOSE также должна быть включена.
Если опция CURLOPT_VERBOSE не включена, обратный вызов CURLOPT_DEBUGFUNCTION не вызывается вообще.
Обратный вызов CURLOPT_DEBUGFUNCTION может иметь следующую сигнатуру:
function foo(CurlHandle $curlHandle, int $type, string $data): void {}CurlHandle $curlHandle: ОбъектCurlHandle.int $type: Указывает, какой тип отладочной информации передаётся. Пояснения см. в разделе Типы отладочной информации.string $data: Текущая отладочная информация.
$ch = curl_init('http://example.com');
curl_setopt($ch, CURLOPT_DEBUGFUNCTION,
static function(CurlHandle $ch, int $type, string $data): void {
printf("Debug (%d): %s", $type, $data);
}
);
curl_setopt($ch, CURLOPT_VERBOSE, true);
curl_exec($ch);Выведет:
Debug (0): Host example.com:80 was resolved.
Debug (0): IPv6: ...
Debug (0): IPv4: ...
Debug (0): Trying ...:80...
Debug (0): Connected to example.com (...) port 80
Debug (0): using HTTP/1.x
Debug (2): GET / HTTP/1.1
Host: example.com
Accept: */*
Debug (0): Request completely sent off
...Возвращаемые значения из callable игнорируются.
Использование с CURLINFO_HEADER_OUT
Обратите внимание, что расширение PHP Curl предоставляет нестандартную опцию CURLINFO_HEADER_OUT, возвращающую вывод заголовков запроса Curl. Это не часть libcurl, но расширение Curl использует опцию CURLOPT_DEBUGFUNCTION libcurl для перехвата данных CURLINFO_HEADER_OUT и возврата их с помощью функции curl_getinfo.
Это проблематичное поведение, а также нарушение шаблона, когда константа CURLINFO_ используется в качестве опции Curl. Кроме того, включение «опции» CURLINFO_HEADER_OUT неявно включает CURLOPT_VERBOSE.
Для обеспечения обратной совместимости не допускается включение опции CURLINFO_HEADER_OUT после установки опции CURLOPT_DEBUGFUNCTION, что приводит к исключению ValueError:
$ch = curl_init();
curl_setopt($ch, CURLOPT_DEBUGFUNCTION,static function() {});
curl_setopt($ch, CURLINFO_HEADER_OUT, true);
// ValueError: CURLINFO_HEADER_OUT option must not be set when the CURLOPT_DEBUGFUNCTION option is setУстановка опции CURLOPT_DEBUGFUNCTION после CURLINFO_HEADER_OUT разрешена и переопределяет опцию CURLINFO_HEADER_OUT.
Влияние на обратную совместимость
CURLOPT_DEBUGFUNCTION и ряд констант являются новыми для PHP 8.4. Опция CURLOPT_DEBUGFUNCTION была добавлена в libcurl в libcurl 7.9.6, а поскольку PHP 8.4 требует libcurl 7.61.0 или более поздней версии, все сборки PHP 8.4 Curl будут иметь эту возможность.