README

这是一个基于惊人的 Saloon v2 🤠 库构建的、与框架无关的 Cloudflare Images PHP 客户端。

目录

• 快速入门
• 与 Laravel 一起使用
• 响应数据
• 图片元数据
• 私有图片
• 自定义 ID
• 图片方法
  • get
  • list
  • update
  • delete
  • create
  • createFromUrl
  • getUploadUrl
• 变体方法
  • list

🚀 快速开始

使用 composer 安装。

composer require benbjurstrom/cloudflare-images-php

创建一个新的 api 实例。

use BenBjurstrom\CloudflareImages\CloudflareImages;
...

$api = new CloudflareImages(
    apiToken: $_ENV['CLOUDFLARE_IMAGES_API_TOKEN'],
    accountId: $_ENV['CLOUDFLARE_IMAGES_ACCOUNT_ID']
);

然后使用它来获取现有图片的详细信息。

$id = '2cdc28f0-017a-49c4-9ed7-87056c83901'
$data = $api->images()->get($id);
$data->variants[0]; // https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/2cdc28f0-017a-49c4-9ed7-87056c83901/public

或从图片字符串上传新的图片。

$fileName = 'example.jpg';
$file = file_get_contents($fileName);

$data = $api->images()->create($file, $fileName);
$data->id; // 2cdc28f0-017a-49c4-9ed7-87056c83901

或生成一个一次性上传 URL，允许用户直接上传图片到 Cloudflare，而不暴露您的 API 密钥。

$data = $api->images()->getUploadUrl();
$data->uploadUrl; // https://upload.imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/d63a6953-12b9-4d89-b8d6-083c86289b93

您可以在 Cloudflare 文档 中找到有关直接创建者上传的更多信息。

与 Laravel 一起使用

首先，将您的凭据添加到服务配置文件中。

// config/services.php
'cloudflare' => [
    'api_token' => env('CLOUDFLARE_IMAGES_API_TOKEN'),
    'account_id' => env('CLOUDFLARE_IMAGES_ACCOUNT_ID'),
    'signing_key' => env('CLOUDFLARE_IMAGES_SIGNING_KEY'),
],

在服务提供者中绑定 CloudflareImages 类。

// app/Providers/AppServiceProvider.php
public function register()
{
    $this->app->bind(CloudflareImages::class, function () {
        return new CloudflareImages(
            apiToken: config('services.cloudflare.api_token'),
            accountId: config('services.cloudflare.account_id'),
            signingKey: config('services.cloudflare.signing_key'),
        );
    });
}

然后在应用程序的任何地方使用它。

$data = app(CloudflareImages::class)->images()->get($id);

使用 Saloon 的惊人的 响应记录 测试您的集成。

use Saloon\Laravel\Saloon; // composer require sammyjo20/saloon-laravel "^2.0"
...
Saloon::fake([
    MockResponse::fixture('getImage'),
]);

$id = 'a74a4313-a51d-4837-b5c1-73e4c562ff00';

// The initial request will check if a fixture called "getImage" 
// exists. Because it doesn't exist yet, the real request will be
// sent and the response will be recorded to tests/Fixtures/Saloon/getImage.json.
$imgData = app(CloudflareImages::class)->images()->get($id);

// However, the next time the request is made, the fixture will 
// exist, and Saloon will not make the request again.
$imgData = app(CloudflareImages::class)->images()->get();

响应数据

所有响应都作为数据对象返回。详细信息可以通过检查以下类属性获得

• ImageData
• ImagesData
• UploadUrlData
• VariantData

图片元数据

Cloudflare 允许您为图片附加可修改的键值存储。要在图片链上附加元数据，请在调用 create、createFromUrl、update 或 getUploadUrl 方法之前，将 withMetadata($metadata) 连接到您的 api 实例。例如

$url = 'https://en.wikipedia.org/wiki/File:Example.jpg'
$api->images()->withMetadata(['user_id' => '123'])->createFromUrl($url);

私有图片

Cloudflare 允许您配置一个图片只能通过带有签名 URL 令牌的方式来访问。要在调用 create、createFromUrl、update 或 getUploadUrl 方法之前使图片私有，请将 private(true) 连接到您的 api 实例。例如

$api->images()->private(true)->getUploadUrl();

要生成签名，请使用可选的签名密钥参数实例化您的 api，然后将您想要签名的 URL 传递给 signUrl 方法。

$api = new CloudflareImages(
    ...
    $signingKey: $_ENV['CLOUDFLARE_IMAGES_SIGNING_KEY']
);

$url = 'https://imagedelivery.net/2222222222222222222222/00000000-0000-0000-0000-000000000000/public';
$api->signUrl($url); // https://imagedelivery.net/2222222222222222222222/00000000-0000-0000-0000-000000000000/public?sig=8217cb17667a1f1af8ed722124d7a5da9543df9e3040a51f3de6e3023812ab3

您可以在 Cloudflare 文档 中找到有关提供私有图片的更多信息。

自定义 ID

如果需要，Cloudflare 允许您配置自定义标识符。要这样做，请在调用 create、createFromUrl 或 getUploadUrl 方法之前，将 withCustomId($id) 连接到您的 api 实例。例如

$api->images()->withCustomId('test/image123')->create($file, $fileName);
$data->id; // test/image123

请注意，带有自定义 ID 的图片不能设置为私有。您可以在 Cloudflare 文档 中找到有关自定义 ID 的更多信息。

可用的图片方法

get()

用于获取有关图片的详细信息，例如其文件名、元数据和可用变体。返回 ImageData 对象。

use BenBjurstrom\CloudflareImages\Data\ImageData;
...
$id = '2cdc28f0-017a-49c4-9ed7-87056c83901'
/* @var ImageData $data */
$data = $api->images()->get($id);
$data->variants[0]; // https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/2cdc28f0-017a-49c4-9ed7-87056c83901/public

list()

用于获取图片的分页列表。返回 ImagesData 对象。

use BenBjurstrom\CloudflareImages\Data\ImagesData
...

/* @var ImagesData $data */
$data = $api->images()->list(
    page: 1, // optional
    perPage: 25, // optional
);

$data->images[0]->id; // 00000000-0000-0000-0000-000000000000

create()

用于从图片字符串上传图片。返回 ImageData 对象。

use BenBjurstrom\CloudflareImages\Data\ImageData;
...
$fileName = 'example.jpg';
$file = file_get_contents($fileName);

/* @var ImageData $data */
$data = $api->images()
    ->private(false) // optional
    ->withCustomId('test/image123') // optional
    ->withMetadata(['user_id' => '123']) // optional
    ->create($file, $fileName);
$data->id; // test/image123

createFromUrl()

用于从给定URL添加图片到Cloudflare。返回ImageData对象。

use BenBjurstrom\CloudflareImages\Data\ImageData
...

$url = 'https://en.wikipedia.org/wiki/File:Example.jpg'

/* @var ImageData $data */
$data = $api->images()
    ->private(false) // optional
    ->withMetadata(['user_id' => '123']) // optional
    ->createFromUrl($id);

update()

用于更新图片的元数据或隐私设置。返回ImageData对象。

⚠️ 警告 - 修改图片的隐私设置将改变图片的标识符。

use BenBjurstrom\CloudflareImages\Data\ImageData
...

$id = 'd63a6953-12b9-4d89-b8d6-083c86289b93'

/* @var ImageData $data */
$data = $api->images()
    ->private(false) // optional
    ->withMetadata(['user_id' => '123']) // optional
    ->update($id);

$data->id; // Contains a new id if the privacy setting was changed. If you are tracking IDs be sure to update your database.

delete()

用于删除图片。返回布尔值。

$id = 'd63a6953-12b9-4d89-b8d6-083c86289b93'
$data = $api->images()->delete($id);
$data // true

getUploadUrl()

用于生成一次性上传URL，允许用户直接上传图片到Cloudflare而无需暴露API密钥。返回UploadUrlData对象。

use BenBjurstrom\CloudflareImages\Data\UploadUrlData;
...

/* @var UploadUrlData $data */
$data = $api->images()
    ->withMetadata(['user_id' => '123']) // optional
    ->getUploadUrl();
$data->uploadUrl; // https://upload.imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/d63a6953-12b9-4d89-b8d6-083c86289b93

您可以在 Cloudflare 文档 中找到有关直接创建者上传的更多信息。

变体方法

list()

用于获取所有变体的列表。返回VariantsData对象。

use BenBjurstrom\CloudflareImages\Data\VariantsData
...

/* @var VariantsData $data */
$data = $api->variants()->all()
$data->variants[0]->id; // public
$data->variants[0]->width; // 1366
$data->variants[0]->height; // 768