PHP curl_setopt_array 函数
最后修改日期：2025 年 4 月 11 日
PHP curl_setopt_array 函数为 cURL 会话设置多个选项。它比单独使用 curl_setopt 设置选项更有效。此函数对于复杂的 cURL 配置特别有用。
基本定义
curl_setopt_array 函数为 cURL 传输设置多个选项。它以 cURL 句柄和选项数组作为参数。如果所有选项都已成功设置，则返回 TRUE。
语法：curl_setopt_array(CurlHandle $handle, array $options): bool。句柄必须使用 curl_init() 创建。选项数组包含 cURL 常量及其值的键值对。
使用 curl_setopt_array 的基本 GET 请求
此示例演示了使用 curl_setopt_array 的简单 GET 请求。
<?php
declare(strict_types=1);
$ch = curl_init();
$options = [
CURLOPT_URL => "https://jsonplaceholder.typicode.com/posts/1",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HEADER => false
];
if (!curl_setopt_array($ch, $options)) {
throw new Exception("Failed to set cURL options");
}
$response = curl_exec($ch);
if ($response === false) {
echo "cURL Error: " . curl_error($ch);
} else {
echo $response;
}
curl_close($ch);
此代码使用 curl_setopt_array 获取一个示例文帖。我们在一个数组中定义所有选项并一次性设置它们。错误处理会检查选项是否已正确设置。响应作为字符串返回。
带 JSON 数据的 POST 请求
此示例展示了使用 curl_setopt_array 的带 JSON 数据的 POST 请求。
<?php
declare(strict_types=1);
$ch = curl_init();
$postData = json_encode([
'title' => 'New Post',
'body' => 'This is the content',
'userId' => 1
]);
$options = [
CURLOPT_URL => "https://jsonplaceholder.typicode.com/posts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $postData,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Content-Length: ' . strlen($postData)
]
];
if (!curl_setopt_array($ch, $options)) {
throw new Exception("Failed to set cURL options");
}
$response = curl_exec($ch);
if ($response === false) {
echo "cURL Error: " . curl_error($ch);
} else {
echo "Response: " . $response;
}
curl_close($ch);
我们创建一个带 JSON 数据的 POST 请求。选项数组包括标头和 POST 字段。JSON 数据被正确编码，其长度设置在标头中。这种方法比多个 curl_setopt 调用更简洁。
使用 curl_setopt_array 进行身份验证
此示例演示了使用 curl_setopt_array 的 HTTP 基本身份验证。
<?php
declare(strict_types=1);
$ch = curl_init();
$options = [
CURLOPT_URL => "https://api.example.com/protected",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
CURLOPT_USERPWD => "username:password",
CURLOPT_SSL_VERIFYPEER => true,
CURLOPT_TIMEOUT => 30
];
if (!curl_setopt_array($ch, $options)) {
throw new Exception("Failed to set cURL options");
}
$response = curl_exec($ch);
if ($response === false) {
echo "cURL Error: " . curl_error($ch);
} else {
echo $response;
}
curl_close($ch);
我们在一个数组中配置身份验证和安全选项。该示例包括 HTTP 基本身份验证凭据和 SSL 验证。超时可防止请求无限期挂起。所有选项都一次性设置以提高清晰度。
带进度的文件下载
此示例演示了如何带进度下载文件，使用 curl_setopt_array。
<?php
declare(strict_types=1);
function progressCallback($resource, $download_size, $downloaded, $upload_size, $uploaded) {
if ($download_size > 0) {
$percent = round($downloaded / $download_size * 100);
echo "Downloaded: $percent%\r";
}
}
$ch = curl_init();
$file = fopen("download.zip", "w");
$options = [
CURLOPT_URL => "https://example.com/largefile.zip",
CURLOPT_FILE => $file,
CURLOPT_NOPROGRESS => false,
CURLOPT_PROGRESSFUNCTION => 'progressCallback',
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_TIMEOUT => 300
];
if (!curl_setopt_array($ch, $options)) {
fclose($file);
throw new Exception("Failed to set cURL options");
}
$response = curl_exec($ch);
fclose($file);
curl_close($ch);
if ($response === false) {
echo "Download failed: " . curl_error($ch);
} else {
echo "\nDownload completed successfully";
}
此代码在显示进度的同时下载文件。我们使用 CURLOPT_FILE 将数据直接写入磁盘。进度回调函数显示下载百分比。所有文件处理和 cURL 选项都在一个数组中配置，以提高清晰度。
带标头的复杂 API 请求
此示例演示了带多个标头的复杂 API 请求。
<?php
declare(strict_types=1);
$ch = curl_init();
$options = [
CURLOPT_URL => "https://api.example.com/v2/data",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode(['status' => 'active']),
CURLOPT_HTTPHEADER => [
'Authorization: Bearer abc123xyz456',
'Content-Type: application/json',
'X-Request-ID: ' . uniqid(),
'Accept: application/json',
'Cache-Control: no-cache'
],
CURLOPT_SSL_VERIFYPEER => true,
CURLOPT_SSL_VERIFYHOST => 2,
CURLOPT_TIMEOUT => 30,
CURLOPT_CONNECTTIMEOUT => 10
];
if (!curl_setopt_array($ch, $options)) {
throw new Exception("Failed to set cURL options");
}
$response = curl_exec($ch);
if ($response === false) {
echo "cURL Error: " . curl_error($ch);
} else {
$data = json_decode($response, true);
print_r($data);
}
curl_close($ch);
此示例展示了一个带多个标头和安全选项的 PUT 请求。我们包括身份验证、内容类型和自定义标头。为安全起见，配置了 SSL 验证和超时。响应被解码为 JSON。
最佳实践
- 选项验证：始终检查 curl_setopt_array 的返回值。
- 错误处理：为请求实现适当的错误处理。
- 安全：为 HTTPS 请求启用 SSL 验证。
- 超时：设置合理的超时值。
- 资源清理：正确关闭句柄和文件。
来源
本教程通过实际示例介绍了 PHP curl_setopt_array 函数，展示了它在各种 HTTP 请求场景下的用法。