使用Guzzle对接Cloudflare图片服务实现带自定义ID的图片直传

以下实现基于Guzzle 7.x稳定版，完全对齐官方给出的curl调用逻辑，支持本地文件直传、上传时指定自定义图片ID的需求。

前置依赖安装 #

如果项目还没安装Guzzle，先在项目根目录执行composer命令安装：
composer require guzzlehttp/guzzle:^7.0

可直接运行的代码示例 #

将代码里的占位符替换成你自己的实际配置即可使用：

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

use GuzzleHttp\Client;
use GuzzleHttp\RequestOptions;

// 替换为你的实际配置
$accountId = '<YOUR_CLOUDFLARE_ACCOUNT_ID>';
$apiToken = '<YOUR_CLOUDFLARE_API_TOKEN>';
$localImagePath = '/path/to/image/c1.jpg'; // 本地图片绝对路径
$customImageId = 'test_123456'; // 要指定的自定义图片ID

$client = new Client([
    'base_uri' => 'https://api.cloudflare.com/',
    'timeout'  => 30.0, // 上传大文件可适当调大该值
]);

try {
    $response = $client->post(
        "client/v4/accounts/{$accountId}/images/v1",
        [
            RequestOptions::HEADERS => [
                'Authorization' => "Bearer {$apiToken}",
            ],
            RequestOptions::MULTIPART => [
                [
                    'name'     => 'file',
                    'contents' => fopen($localImagePath, 'r'),
                    'filename' => basename($localImagePath),
                ],
                [
                    'name'     => 'id',
                    'contents' => $customImageId,
                ]
            ],
        ]
    );

    $result = json_decode($response->getBody()->getContents(), true);
    
    if ($result['success']) {
        echo "上传成功，图片ID：{$result['result']['id']}";
        // 可根据业务需求自行处理返回的图片访问地址、变体配置等字段
    } else {
        echo "上传失败，错误详情：" . print_r($result['errors'], true);
    }
} catch (\GuzzleHttp\Exception\ClientException $e) {
    // 捕获接口返回的业务错误，比如令牌无权限、ID重复、文件格式不合法等
    $errorResp = json_decode($e->getResponse()->getBody()->getContents(), true);
    echo "请求错误：" . print_r($errorResp['errors'] ?? $e->getMessage(), true);
} catch (\Exception $e) {
    echo "运行错误：" . $e->getMessage();
}

常见踩坑说明 #

• 不要用form_params传参：该接口要求multipart/form-data格式，必须使用Guzzle的multipart配置项，用form_params会直接报参数缺失错误。
• 文件字段必须传资源句柄：不要直接把本地文件路径字符串传给contents参数，必须用fopen()打开文件流，才能和curl里@文件路径的上传行为一致。
• 自定义ID符合规则：自定义ID长度不能超过1024字符，不能包含/字符，传入重复ID时接口会直接返回错误。
• 令牌权限校验：使用的API令牌必须开通Cloudflare Images - Edit权限，否则会返回403无权限错误。
• 大文件适配：上传10MB以上的图片时，适当调大timeout和connect_timeout配置，避免请求超时中断。

代码和官方curl示例完全一一对应：请求头Authorization配置、file文件上传字段、id自定义参数字段完全匹配curl的传参逻辑，可直接跑通。

内容的提问来源于stack exchange，提问作者marymvlg28