README

简介

Shardimage 应用的官方 PHP 包。

安装

使用 Composer 安装

composer require shardimage/shardimage-php

或者在您的 composer.json 文件中添加

shardimage/shardimage-php:"^1.0"

并运行更新。

快速入门

使用包的简单示例。有关详细信息，请参阅我们的官方文档 >>>

配置客户端

使用网站上的信息配置客户端以连接到 Shardimage API。

use shardimage\shardimagephp\auth\Client;

$client = new Client([
    'apiKey' => '<apiKey>',             //key to use the API or the image serving
    'apiSecret' => '<apiSecret>',       //secret to use the API
    'imageSecret' => '<imageSecret>',    //secret to gain more security on image serving
    'cloudId' => '<cloudId>',           //default configuration for cloud ID, it can be overwritten in later usage
]);

获取访问数据

您的 apiKey 和 apiSecret 可在 Shardimage API 页面上找到。

通过 Shardimage API 可以创建访问令牌，它需要一个配置了 apiKey 和 apiSecret 的客户端。

use shardimage\shardimagephp\models\accesstoken\ImageUrlAccessToken;

$accessToken = new ImageUrlAccessToken();
$accessToken->expiry = time() + 3600;
$accessToken->limit = 1000;
$accessToken->extra = [
    'secret' => 'secretString', //<apiAccessTokenSecret>
];

$accessToken = $client->getAccessTokenService()->create($accessToken);
if ($accessToken instanceof ImageUrlAccessToken) {
    echo $accessToken->id; //<apiAccessToken>
}

现在我们可以为令牌图像托管配置另一个客户端

use shardimage\shardimagephp\auth\Client;

$tokenClient = new Client([
    'apiAccessToken' => <apiAccessToken>,
    'apiAccessTokenSecret' => <apiAccessTokenSecret>, //optional, 
]);

使用 API 管理云

要上传和存储图像，必须创建云。

use shardimage\shardimagephp\models\cloud\Cloud;
use shardimage\shardimagephp\services\CloudService;

$cloud = new Cloud([
    'name' => 'First Cloud',
    'description' => 'My first Shardimage cloud ever. Awesome!',
]);

您可以为您的云添加功能以提高其效率和安全性！要查看我们的全部功能列表，请参阅文档 >>>

注意：只有在设置了客户端的安全信息：图像密钥哈希或访问令牌/访问令牌密钥的情况下，deliverySecureUrl 设置才会生效。

$cloud->settings = [
    //...
    "deliverySecureUrl" => [
        "status" => true    //securing image hosting
    ],
    //...
];

发送到 API 创建它。

$cloud = $client->getCloudService()->create($cloud);

如果您已有云，您可以列出它们

use shardimage\shardimagephp\models\cloud\IndexParams;

$indexParams = new IndexParams();
$indexParams->nextPageToken = 0;
$indexParams->projections = [   //with projections parameter, we have the chance to narrow down the returning data.
    IndexParams::PROJECTION_NO_BACKUP,
    IndexParams::PROJECTION_NO_FIREWALL,
];

$response = $client->getCloudService()->index($indexParams);

使用 API 管理图像

要将图像上传到云或从云中列出，我们需要使用云的 ID。Shardimage PHP 包可以通过单线程或多线程上传图像，如果您有大量图片。

单线程

$file = __DIR__ . '/' . $file;
$fileName = 'Example';
$result = $client->getUploadService()->upload([
    'file' => $file,
    'cloudId' => <cloudId>,
    'publicId' => $fileName,
], [    //optional parameters
    'tags' => [
        'example',
        'dump'
    ],
]);

如果一切顺利，$result 变量将包含包含上传图像数据的 shardimage\shardimagephp\models\image\Image 对象。

多线程上传与单线程类似，我们需要在上传之前开启 defer 选项。关闭它将发送收集到的数据。

use shardimage\shardimagephp\helpers\UploadHelper;

$files = [
    'file1.jpg',
    'file2.jpg',
    'file3.png',
    'file4.webp',
    'file5.gif',
];
$client->defer(true); //turning on
foreach ($files as $file) {
    $client->getUploadService()->upload([
        'file' => $file,
        'publicId' => UploadHelper::generateRandomPublicId(32),
    ], [
        'tags' => [
            'batch',
            'examples',
        ],
    ]);
}
$result = $client->defer(false); //without turning off, nothing will happen

可以通过两种方法从系统中删除不需要的图片。简单删除将根据公共 ID 和云 ID 删除一个图像。

$client->getImageService()->delete([
    'publicId' => <publicId>,
    'cloudId' => <cloudId>,
]);

另一种方法是按标签删除图像。在这种情况下，所有具有给定标签的图像都将从目标云中删除。

$client->getImageService()->delete([
    'cloudId' => <cloudId>,
    'tag' => '<tag>',
]);

使用 UploadBuilder

使用构建器类可以简化上传，通过为开发者提供构建上传参数的开发友好方式。

use shardimage\shardimagephp\builders\UploadBuilder;

$builder = (new UploadBuilder())
    ->withPrefix('SDK-TEST-')
    ->withRandomPublicId(16)
    ->withTags(['tag1'])
    ->withAddedTags(['added-tag'])
    ->withFilePath($filePath);
$result = $client->getUploadService()->upload($builder->build());

托管图像

使用 packgate 托管上传的图像基本上是生成它们的 URL。使用 UrlService 类，您也可以构建远程图像 URL，并通过 Shardimage 提供服务。实际上，Shardimage 只会存储原始上传的图像。所有修改、转换和转换都通过 URL 规则或云设置应用。有关更多信息，请参阅文档 >>>

生成存储图像 URL 的示例

$transformation = Transformation::create();
$transformation->width(200)->height(200)->group();
$url = $client->getUrlService()->create([
    'cloudId' => <cloudId>,
    'publicId' => <publicId>,
], [
    'transformation' => $transformation,
    'security' => 'basic',
]);
echo $url; //https://img.shardimage.com/<cloudId>/s-b3:<securehash>/w:200_h:200/i/<publicId>

只有在您在客户端配置中设置了 imageSecret 时，才会将基本安全哈希添加到 URL 中。

更新日志

本项目的所有重大更改都将记录在 CHANGELOG 文件中。

格式基于 Keep a Changelog，本项目遵循 语义化版本控制。

许可证

阅读更多 >>

链接

• Shardimage
• Shardimage 文档
• Shardimage 博客