PHP curl_upkeep 函数
最后修改日期：2025 年 4 月 11 日
PHP curl_upkeep 函数对 cURL 句柄执行连接维护检查。它通过检查 HTTP/2 连接的健康状况来帮助维护持久的 HTTP/2 连接。此函数随 cURL 7.62.0 在 PHP 7.3.0 中引入。
基本定义
curl_upkeep 函数检查 HTTP/2 连接的健康状况。成功时返回 TRUE，失败时返回 FALSE。该函数将 cURL 句柄作为其唯一参数。
语法：curl_upkeep(CurlHandle $handle): bool。句柄必须是活动的 HTTP/2 连接。此函数有助于防止长期 HTTP/2 连接的连接超时。
基本连接维护
本示例演示了使用 HTTP/2 连接进行 curl_upkeep 的基本用法。
basic_upkeep.php
<?php
declare(strict_types=1);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://http2.golang.org/");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_2_0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// Initial request
curl_exec($ch);
// Perform connection upkeep
if (curl_upkeep($ch)) {
echo "Connection is healthy\n";
} else {
echo "Connection check failed: " . curl_error($ch) . "\n";
}
curl_close($ch);
此代码建立 HTTP/2 连接并执行健康检查。curl_upkeep 调用验证连接是否仍然活动。请注意，HTTP/2 服务器支持对于此功能正常工作是必需的。
带维护的持久连接
本示例展示了如何通过定期维护来保持持久连接。
persistent_connection.php
<?php
declare(strict_types=1);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://http2.golang.org/");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_2_0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// Initial request
$response = curl_exec($ch);
echo "Initial request: " . substr($response, 0, 50) . "...\n";
// Wait 30 seconds
sleep(30);
// Perform upkeep before next request
if (curl_upkeep($ch)) {
$response = curl_exec($ch);
echo "Second request: " . substr($response, 0, 50) . "...\n";
} else {
echo "Connection lost, need to reinitialize\n";
}
curl_close($ch);
我们使用 curl_upkeep 在请求之间维护连接。这对于向同一服务器发出多个请求的应用程序很有用。维护检查有助于避免请求之间的连接超时。
带错误处理的连接维护
本示例演示了 curl_upkeep 的正确错误处理。
error_handling.php
<?php
declare(strict_types=1);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://http2.golang.org/");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_2_0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// Initial request
curl_exec($ch);
// Simulate network issue by changing timeout
curl_setopt($ch, CURLOPT_TIMEOUT, 1);
// Perform upkeep with error handling
$upkeepResult = curl_upkeep($ch);
if ($upkeepResult === false) {
$errno = curl_errno($ch);
$error = curl_error($ch);
echo "Upkeep failed (errno $errno): $error\n";
// Reinitialize connection if needed
curl_close($ch);
$ch = curl_init();
// ... reinitialize options ...
} else {
echo "Connection is healthy\n";
}
curl_close($ch);
我们演示了如何处理潜在的维护故障。代码检查返回值并在维护失败时检查错误详细信息。这种模式对于生产应用程序中健壮的连接管理非常重要。
连接池中的维护
本示例展示了如何使用 curl_upkeep 管理多个连接。
connection_pool.php
<?php
declare(strict_types=1);
// Initialize multiple HTTP/2 connections
$connections = [];
$urls = [
"https://http2.golang.org/",
"https://http2.akamai.com/",
"https://nghttp2.org/"
];
foreach ($urls as $url) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_2_0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_exec($ch); // Establish connection
$connections[] = $ch;
}
// Periodically check all connections
foreach ($connections as $i => $ch) {
echo "Checking connection $i: ";
if (curl_upkeep($ch)) {
echo "OK\n";
} else {
echo "FAILED - " . curl_error($ch) . "\n";
// Mark for reinitialization
unset($connections[$i]);
curl_close($ch);
}
}
// Clean up remaining connections
foreach ($connections as $ch) {
curl_close($ch);
}
此示例维护多个 HTTP/2 连接并检查其健康状况。代码演示了如何通过定期维护检查来管理连接池。失败的连接会从池中移除并妥善关闭。
带自定义间隔的维护
本示例根据连接年龄实现了自定义维护间隔。
custom_interval.php
<?php
declare(strict_types=1);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://http2.golang.org/");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_2_0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$lastUsed = time();
$connectionAge = 0;
// Main application loop
for ($i = 0; $i < 5; $i++) {
// Perform request
$response = curl_exec($ch);
echo "Request $i: " . substr($response, 0, 20) . "...\n";
// Update last used time
$lastUsed = time();
// Wait random time (simulate application work)
$waitTime = rand(10, 30);
sleep($waitTime);
// Calculate connection age
$connectionAge = time() - $lastUsed;
// Perform upkeep if connection is idle
if ($connectionAge > 15) {
echo "Performing upkeep (idle for $connectionAge seconds)\n";
if (!curl_upkeep($ch)) {
echo "Upkeep failed, reinitializing connection\n";
curl_close($ch);
$ch = curl_init();
// Reinitialize options...
$lastUsed = time();
}
}
}
curl_close($ch);
此代码实现了基于连接空闲时间的自定义维护策略。只有当连接空闲超过 15 秒时才会执行维护。此方法通过最大限度地减少不必要的维护检查来优化性能。
最佳实践
- 仅限 HTTP/2： curl_upkeep 仅适用于 HTTP/2 连接。
- 错误处理： 始终检查 curl_upkeep 的返回值。
- 时机： 在空闲时段进行维护，而不是在请求期间。
- 重新初始化： 准备好重新创建失败的连接。
- 测试： 验证服务器对 HTTP/2 和连接维护的支持。
来源
本教程介绍了 PHP curl_upkeep 函数，并通过实际示例展示了其在维护 HTTP/2 连接方面的用法。适当的连接管理可以显著提高 HTTP/2 应用程序的性能。