PHP curl_setopt 函数
最后修改日期：2025 年 4 月 11 日
PHP curl_setopt 函数用于设置 cURL 传输的选项。在执行之前配置 cURL 句柄至关重要。选项控制着 URL、头部和传输行为等各种方面。
基本定义
curl_setopt 函数用于设置给定 cURL 会话句柄上的一个选项。成功时返回 TRUE，失败时返回 FALSE。该函数接受三个参数：句柄 (handle)、选项 (option) 和值 (value)。
语法：curl_setopt(CurlHandle $handle, int $option, mixed $value): bool。句柄必须通过 curl_init() 创建。有数百个选项可用于自定义 cURL 的行为。
设置基本选项
此示例演示了为 GET 请求设置基本 cURL 选项。
<?php
declare(strict_types=1);
$ch = curl_init();
// Set the target URL
curl_setopt($ch, CURLOPT_URL, "https://api.example.com/data");
// Return the transfer as a string
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// Set timeout to 30 seconds
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
// Follow redirects
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
$response = curl_exec($ch);
if ($response === false) {
echo "cURL Error: " . curl_error($ch);
} else {
echo $response;
}
curl_close($ch);
此代码配置了可靠的 HTTP 请求所需的关键选项。CURLOPT_RETURNTRANSFER 使 curl_exec 返回响应。CURLOPT_TIMEOUT 防止挂起，而 CURLOPT_FOLLOWLOCATION 处理重定向。
带 JSON 数据的 POST 请求
此示例展示了如何配置带有 JSON 载荷的 POST 请求。
<?php
declare(strict_types=1);
$ch = curl_init();
$data = [
'name' => 'John Doe',
'email' => 'john@example.com'
];
$jsonData = json_encode($data);
curl_setopt($ch, CURLOPT_URL, "https://api.example.com/users");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Content-Length: ' . strlen($jsonData)
]);
$response = curl_exec($ch);
if ($response === false) {
echo "cURL Error: " . curl_error($ch);
} else {
echo "Response: " . $response;
}
curl_close($ch);
我们配置了一个带 JSON 数据的 POST 请求。CURLOPT_POST 设置了请求方法，而 CURLOPT_POSTFIELDS 包含了 JSON 载荷。头部指定了内容类型和长度，以确保正确的 API 通信。
自定义请求头部
此示例演示了为 API 身份验证设置自定义 HTTP 头部。
<?php
declare(strict_types=1);
$ch = curl_init();
$headers = [
'Authorization: Bearer abc123xyz456',
'X-API-Version: 2.0',
'Accept: application/json',
'Cache-Control: no-cache'
];
curl_setopt($ch, CURLOPT_URL, "https://api.example.com/protected");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_HEADER, true); // Include headers in output
$response = curl_exec($ch);
if ($response === false) {
echo "cURL Error: " . curl_error($ch);
} else {
echo $response;
}
curl_close($ch);
我们设置了多个自定义头部，包括一个授权令牌。CURLOPT_HTTPHEADER 接受一个头部字符串数组。CURLOPT_HEADER 在输出中包含响应头部，用于调试。
带进度的文件下载
此示例展示了如何使用进度回调函数下载文件。
<?php
declare(strict_types=1);
function progressCallback($download_size, $downloaded, $upload_size, $uploaded) {
if ($download_size > 0) {
$percent = round($downloaded / $download_size * 100);
echo "Downloaded: $percent% ($downloaded/$download_size bytes)\n";
}
}
$ch = curl_init();
$file = fopen("download.zip", 'w');
curl_setopt($ch, CURLOPT_URL, "https://example.com/largefile.zip");
curl_setopt($ch, CURLOPT_FILE, $file);
curl_setopt($ch, CURLOPT_NOPROGRESS, false);
curl_setopt($ch, CURLOPT_PROGRESSFUNCTION, 'progressCallback');
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
$result = curl_exec($ch);
fclose($file);
if ($result === false) {
echo "Download failed: " . curl_error($ch);
} else {
echo "Download completed successfully";
}
curl_close($ch);
此代码在显示进度的同时下载文件。CURLOPT_FILE 直接写入文件句柄。进度回调函数会接收下载统计信息。这对于大文件非常高效，因为它避免了内存问题。
SSL 证书验证
此示例演示了正确的 SSL 证书验证设置。
<?php
declare(strict_types=1);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://secure.example.com");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// Enable SSL verification (recommended for production)
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
// Specify CA bundle path
curl_setopt($ch, CURLOPT_CAINFO, "/path/to/cacert.pem");
// For debugging SSL issues (remove in production)
// curl_setopt($ch, CURLOPT_VERBOSE, true);
$response = curl_exec($ch);
if ($response === false) {
echo "SSL Error: " . curl_error($ch);
} else {
echo "Secure connection established";
// Process $response...
}
curl_close($ch);
此配置确保了正确的 SSL 证书验证。CURLOPT_SSL_VERIFYPEER 验证对等方的证书。CURLOPT_SSL_VERIFYHOST 检查证书名称是否与主机匹配。在生产环境中务必使用正确的验证。
最佳实践
- 错误处理：始终检查 curl_setopt 的返回值。
- 清理：使用后通过 curl_close 关闭句柄。
- SSL 安全：为 HTTPS 请求启用验证。
- 超时：设置合理的超时值。
- 内存：大文件下载使用 CURLOPT_FILE。
来源
本教程通过实际示例介绍了 PHP curl_setopt 函数，展示了其在各种 HTTP 请求配置中的用法。