35. PHP cURL

cURL 是 PHP 最强大的 HTTP 客户端。调用 API、抓取网页、上传文件，它都能胜任。

35.1 cURL 基础流程

所有 cURL 请求都遵循”初始化 -> 设置选项 -> 执行 -> 关闭”四步：

<?php
// 1. 初始化
$ch = curl_init();

// 2. 设置选项
curl_setopt($ch, CURLOPT_URL, "https://api.github.com/users/php");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // 返回字符串而非直接输出

// 3. 执行
$response = curl_exec($ch);

// 4. 检查错误
if ($response === false) {
    echo "cURL 错误：" . curl_error($ch);
} else {
    echo $response;
}

// 5. 关闭
curl_close($ch);

35.2 发起 GET 请求

<?php
function httpGet(string $url, array $headers = []): string {
    $ch = curl_init();

    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); // 跟随重定向
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);          // 超时时间
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true); // 验证 SSL 证书

    if (!empty($headers)) {
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    }

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new Exception("HTTP 状态码：{$httpCode}");
    }

    return $response;
}

// 调用示例
$data = httpGet("https://api.example.com/users");
$users = json_decode($data, true);

35.3 发起 POST 请求

POST JSON 数据

<?php
function httpPost(string $url, array $data, array $headers = []): string {
    $ch = curl_init();

    $json     = json_encode($data);
    $headers  = array_merge([
        "Content-Type: application/json",
        "Content-Length: " . strlen($json),
    ], $headers);

    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

    $response = curl_exec($ch);
    curl_close($ch);

    return $response;
}

// 调用示例
$result = httpPost("https://api.example.com/login", [
    "username" => "admin",
    "password" => "secret123",
]);

POST 表单数据

<?php
$ch = curl_init();

$postData = [
    "name"  => "张三",
    "email" => "zhangsan@example.com",
];

curl_setopt($ch, CURLOPT_URL, "https://api.example.com/form");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postData));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

35.4 常用选项速查

选项	作用
CURLOPT_URL	请求地址
CURLOPT_RETURNTRANSFER	返回响应字符串
CURLOPT_POST	使用 POST 方法
CURLOPT_POSTFIELDS	POST 数据
CURLOPT_HTTPHEADER	自定义请求头数组
CURLOPT_FOLLOWLOCATION	跟随 3xx 重定向
CURLOPT_TIMEOUT	超时秒数
CURLOPT_SSL_VERIFYPEER	验证 SSL 证书
CURLOPT_USERAGENT	设置 User-Agent

35.5 获取响应信息

<?php
$ch = curl_init("https://httpbin.org/get");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

// 获取详细的传输信息
$info = curl_getinfo($ch);
echo "HTTP 码：" . $info["http_code"] . "\n";
echo "总耗时：" . $info["total_time"] . " 秒\n";
echo "内容类型：" . ($info["content_type"] ?? "未知") . "\n";

curl_close($ch);

35.6 下载文件

<?php
$url  = "https://example.com/image.jpg";
$save = "downloads/photo.jpg";

$ch = curl_init($url);
$fp = fopen($save, "wb");

curl_setopt($ch, CURLOPT_FILE, $fp);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);

curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

curl_close($ch);
fclose($fp);

if ($code === 200) {
    echo "下载成功，保存为 {$save}";
} else {
    unlink($save);
    echo "下载失败，HTTP 码：{$code}";
}

35.7 封装可复用的请求类

<?php
class HttpClient {
    public static function request(
        string $method,
        string $url,
        array $data = [],
        array $headers = []
    ): array {
        $ch = curl_init();

        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 30);

        if (strtoupper($method) === "POST") {
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
            $headers[] = "Content-Type: application/json";
        }

        if (!empty($headers)) {
            curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        }

        $body = curl_exec($ch);
        $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        $error = curl_error($ch);
        curl_close($ch);

        return [
            "code"    => $code,
            "body"    => $body,
            "error"   => $error,
            "json"    => json_decode($body, true),
        ];
    }
}

// 使用
$result = HttpClient::request("GET", "https://api.example.com/data");
if ($result["code"] === 200) {
    print_r($result["json"]);
}

---