PHP curl_multi_setopt 函数
最后修改日期：2025 年 4 月 11 日
PHP curl_multi_setopt 函数为 cURL Multi 句柄设置选项。它用于配置多个并发 cURL 传输的行为。此函数与 curl_multi_init() 创建的句柄一起使用。
基本定义
curl_multi_setopt 函数为给定的 cURL Multi 句柄设置一个选项。成功时返回 TRUE，失败时返回 FALSE。该函数接受三个参数。
语法：curl_multi_setopt(CurlMultiHandle $multi_handle, int $option, mixed $value): bool。Multi 句柄必须使用 curl_multi_init() 创建。选项会影响 Multi 句柄如何处理多个传输。
设置 Pipeline 选项
此示例演示如何为多个请求启用 HTTP Pipelining。
pipeline_option.php
<?php
declare(strict_types=1);
$mh = curl_multi_init();
// Enable HTTP pipelining
curl_multi_setopt($mh, CURLMOPT_PIPELINING, CURLPIPE_HTTP1 | CURLPIPE_MULTIPLEX);
$ch1 = curl_init("https://example.com/api1");
$ch2 = curl_init("https://example.com/api2");
curl_setopt($ch1, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true);
curl_multi_add_handle($mh, $ch1);
curl_multi_add_handle($mh, $ch2);
// Execute the multi handle
$running = null;
do {
curl_multi_exec($mh, $running);
} while ($running > 0);
// Get responses
$response1 = curl_multi_getcontent($ch1);
$response2 = curl_multi_getcontent($ch2);
// Clean up
curl_multi_remove_handle($mh, $ch1);
curl_multi_remove_handle($mh, $ch2);
curl_multi_close($mh);
此代码为多个请求启用 HTTP Pipelining。CURLMOPT_PIPELINING 允许通过同一连接发送请求。当向同一服务器发出多个请求时，这可以提高性能。
设置最大主机连接数
此示例展示如何限制到单个主机的连接数。
max_host_connections.php
<?php
declare(strict_types=1);
$mh = curl_multi_init();
// Limit to 2 connections per host
curl_multi_setopt($mh, CURLMOPT_MAX_HOST_CONNECTIONS, 2);
$handles = [];
$urls = [
"https://api.example.com/users/1",
"https://api.example.com/users/2",
"https://api.example.com/users/3",
"https://api.example.com/users/4"
];
foreach ($urls as $url) {
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_multi_add_handle($mh, $ch);
$handles[] = $ch;
}
// Execute the multi handle
$running = null;
do {
curl_multi_exec($mh, $running);
curl_multi_select($mh);
} while ($running > 0);
// Process responses
foreach ($handles as $ch) {
echo curl_multi_getcontent($ch) . "\n";
curl_multi_remove_handle($mh, $ch);
curl_close($ch);
}
curl_multi_close($mh);
我们使用 CURLMOPT_MAX_HOST_CONNECTIONS 将到同一主机的连接限制为 2。这可以防止因过多的并发连接而使服务器过载。当达到限制时，Multi 句柄将排队请求。
设置最大总连接数
此示例演示如何限制并发连接的总数。
max_total_connections.php
<?php
declare(strict_types=1);
$mh = curl_multi_init();
// Limit to 3 total connections
curl_multi_setopt($mh, CURLMOPT_MAXCONNECTS, 3);
$handles = [];
$urls = [
"https://api1.example.com",
"https://api2.example.com",
"https://api3.example.com",
"https://api4.example.com",
"https://api5.example.com"
];
foreach ($urls as $url) {
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_multi_add_handle($mh, $ch);
$handles[] = $ch;
}
// Execute the multi handle
$running = null;
do {
curl_multi_exec($mh, $running);
curl_multi_select($mh);
} while ($running > 0);
// Process responses
foreach ($handles as $ch) {
echo curl_multi_getcontent($ch) . "\n";
curl_multi_remove_handle($mh, $ch);
curl_close($ch);
}
curl_multi_close($mh);
CURLMOPT_MAXCONNECTS 将所有并发连接限制为 3。这在向多个不同主机发出请求时很有用。当达到全局连接限制时，Multi 句柄将排队请求。
设置 Socket 回调
此示例展示如何使用 Socket 回调进行监控。
socket_callback.php
<?php
declare(strict_types=1);
function socket_callback($mh, $timeout_ms) {
// Custom logic to handle socket activity
echo "Socket callback called with timeout: $timeout_ms ms\n";
return 0;
}
$mh = curl_multi_init();
// Set socket callback function
curl_multi_setopt($mh, CURLMOPT_SOCKETFUNCTION, 'socket_callback');
$ch1 = curl_init("https://example.com/api1");
$ch2 = curl_init("https://example.com/api2");
curl_setopt($ch1, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true);
curl_multi_add_handle($mh, $ch1);
curl_multi_add_handle($mh, $ch2);
// Execute the multi handle
$running = null;
do {
curl_multi_exec($mh, $running);
} while ($running > 0);
// Get responses
$response1 = curl_multi_getcontent($ch1);
$response2 = curl_multi_getcontent($ch2);
// Clean up
curl_multi_remove_handle($mh, $ch1);
curl_multi_remove_handle($mh, $ch2);
curl_multi_close($mh);
CURLMOPT_SOCKETFUNCTION 设置一个用于 Socket 活动监控的回调。该回调接收 Multi 句柄和超时值。这允许在 Socket 准备好读/写时执行自定义逻辑。
设置 Timer 回调
此示例演示如何使用 Timer 回调进行超时控制。
timer_callback.php
<?php
declare(strict_types=1);
function timer_callback($mh, $timeout_ms) {
// Custom timeout handling logic
echo "Timer callback called with timeout: $timeout_ms ms\n";
return 0;
}
$mh = curl_multi_init();
// Set timer callback function
curl_multi_setopt($mh, CURLMOPT_TIMERFUNCTION, 'timer_callback');
$ch1 = curl_init("https://example.com/api1");
$ch2 = curl_init("https://example.com/api2");
curl_setopt($ch1, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true);
curl_multi_add_handle($mh, $ch1);
curl_multi_add_handle($mh, $ch2);
// Execute the multi handle
$running = null;
do {
curl_multi_exec($mh, $running);
} while ($running > 0);
// Get responses
$response1 = curl_multi_getcontent($ch1);
$response2 = curl_multi_getcontent($ch2);
// Clean up
curl_multi_remove_handle($mh, $ch1);
curl_multi_remove_handle($mh, $ch2);
curl_multi_close($mh);
CURLMOPT_TIMERFUNCTION 设置一个用于超时控制的回调。该回调接收 Multi 句柄和超时值（以毫秒为单位）。这允许实现自定义超时处理逻辑。
最佳实践
- 连接限制： 使用 CURLMOPT_MAX_HOST_CONNECTIONS 来礼貌地对待服务器。
- 性能： 在向同一主机发出多个请求时启用 Pipelining。
- 资源管理： 始终使用 curl_multi_remove_handle 清理句柄。
- 错误处理： 检查 curl_multi_setopt 调用的返回值。
- 监控： 使用回调对传输进行高级控制。
来源
本教程介绍了 PHP curl_multi_setopt 函数，并通过实际示例展示了其在配置多个 cURL 传输方面的用法。