php 网络请求工具全解：cURL 与 Guzzle 总结

一、PHP cURL 全面总结

cURL 是 PHP 内置的网络请求扩展，支持 HTTP/HTTPS/FTP 等多种协议，是处理网络通信的基础工具。

1. cURL 核心使用流程

cURL 的标准流程分为四步：初始化 → 设置选项 → 执行请求 → 关闭会话。

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

if ($ch === false) {
    die("cURL 初始化失败");
}

// 2. 设置请求选项
curl_setopt_array($ch, [
    CURLOPT_URL => "https://api.example.com/data",
    CURLOPT_RETURNTRANSFER => true, // 响应以字符串返回
    CURLOPT_TIMEOUT => 30,          // 超时时间（秒）
    CURLOPT_SSL_VERIFYPEER => false, // 开发环境可关闭SSL验证
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "Authorization: Bearer your_token"
    ]
]);

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

// 4. 错误处理
if (curl_errno($ch)) {
    $error_msg = curl_error($ch);
    echo "请求失败：" . $error_msg;
}

// 5. 获取响应信息
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$response_info = curl_getinfo($ch);

// 6. 关闭会话
curl_close($ch);

// 处理响应
if ($http_code === 200) {
    $data = json_decode($response, true);
    print_r($data);
} else {
    echo "请求失败，状态码：" . $http_code;
}
?>

---

2. cURL 常见请求类型示例

（1）POST 请求（JSON 数据）

<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => "https://api.example.com/post",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
        "name" => "test",
        "age" => 20
    ]),
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json"
    ]
]);
$response = curl_exec($ch);
curl_close($ch);
?>

（2）文件上传

<?php
$ch = curl_init();
$file_path = realpath("test.jpg");
$post_data = [
    "file" => new CURLFile($file_path, "image/jpeg", "test.jpg")
];
curl_setopt_array($ch, [
    CURLOPT_URL => "https://api.example.com/upload",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $post_data
]);
$response = curl_exec($ch);
curl_close($ch);
?>

---

3. cURL 核心优缺点

|--------------|-------------------------|
| 优点 | 缺点 |
| 内置扩展，无需额外安装 | 代码冗余，每次请求需重复写初始化/关闭逻辑 |
| 支持多种协议 | 错误处理繁琐，需手动判断 curl_errno |
| 底层可控，自定义细节 | 不支持异步请求，性能优化成本高 |
| 兼容性好，支持所有PHP | 处理 JSON/表单数据需手动格式化 |

---

二、Guzzle 扩展使用与总结

Guzzle 是 PHP 生态中最流行的现代化 HTTP 客户端（基于 cURL 封装），极大提升了易用性，支持 PSR-7 标准，是生产环境首选。

1. 安装 Guzzle

使用 Composer 安装（要求 PHP >= 7.2）：

composer require guzzlehttp/guzzle

---

2. Guzzle 核心使用示例

（1）基础 GET 请求

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new Client([
    'base_uri' => 'https://api.example.com',
    'timeout'  => 30.0,
]);

try {
    $response = $client->get('/data', [
        'query' => [
            'page' => 1,
            'size' => 10
        ],
        'headers' => [
            'Authorization' => 'Bearer your_token'
        ]
    ]);

    $status_code = $response->getStatusCode();
    $body = $response->getBody()->getContents();
    $data = json_decode($body, true);
    print_r($data);

} catch (RequestException $e) {
    echo "请求失败：" . $e->getMessage();
    if ($e->hasResponse()) {
        echo "状态码：" . $e->getResponse()->getStatusCode();
    }
}
?>

（2）POST 请求（JSON 数据）

<?php
$client = new Client();
try {
    $response = $client->post('https://api.example.com/post', [
        'json' => [
            'name' => 'test',
            'age' => 20
        ]
    ]);
    $data = json_decode($response->getBody(), true);
} catch (RequestException $e) {
    // 异常处理
}
?>

（3）表单提交（application/x-www-form-urlencoded）

<?php
$client = new Client();
$response = $client->post('https://api.example.com/form', [
    'form_params' => [
        'username' => 'test',
        'password' => '123456'
    ]
]);
?>

（4）文件上传

<?php
$client = new Client();
$response = $client->post('https://api.example.com/upload', [
    'multipart' => [
        [
            'name' => 'file',
            'contents' => fopen('test.jpg', 'r'),
            'filename' => 'test.jpg',
            'headers' => ['Content-Type' => 'image/jpeg']
        ]
    ]
]);
?>

（5）异步请求（Guzzle 核心优势）

<?php
$client = new Client();

$promise1 = $client->getAsync('https://api.example.com/1');
$promise2 = $client->getAsync('https://api.example.com/2');

$results = GuzzleHttp\Promise\unwrap([$promise1, $promise2]);

$response1 = $results[0]->getBody()->getContents();
$response2 = $results[1]->getBody()->getContents();
?>

---

3. Guzzle 核心特性总结

|----------|-------------------------------|
| 特性 | 说明 |
| 简洁的 API | 无需手动初始化/关闭会话，一行代码发送请求 |
| 自动数据格式化 | 内置json/form_params，自动处理编码和请求头 |
| 完善的异常处理 | 统一RequestException捕获所有请求错误 |
| 异步请求 | 支持并发请求，提升多接口调用效率 |
| PSR-7 兼容 | 遵循 PHP 标准，可与主流框架无缝集成 |
| 中间件支持 | 可扩展日志、重试、缓存等功能 |
| 响应便捷操作 | 直接获取状态码、响应头、JSON 解析结果等 |

---

三、cURL vs Guzzle 选型建议

|--------------------|--------|--------------------|
| 场景 | 推荐使用 | 原因 |
| 简单请求/无 Composer 环境 | cURL | 内置扩展，无需额外依赖 |
| 老项目维护（PHP < 7.2） | cURL | Guzzle 对 PHP 版本有要求 |
| 生产环境/复杂请求 | Guzzle | 代码简洁、易维护、支持异步和扩展 |
| 多接口并发调用 | Guzzle | 异步请求大幅提升性能 |
| 框架开发（Laravel/TP等） | Guzzle | 框架集成，符合现代开发规范 |

---

总结

1. PHP cURL：基础工具，内置、兼容性好，适用于简单场景或无 Composer 环境，但代码冗余、易用性较差。
2. Guzzle：cURL 的现代化封装，API 简洁、支持异步、异常处理完善，是生产环境处理 HTTP 请求的首选。
3. 选型建议：简单场景用 cURL，复杂或生产环境优先 Guzzle，框架开发直接集成 Guzzle。

---