README

Introduction

Official PHP package for using Shardimage application.

Installation

Install With Composer

composer require shardimage/shardimage-php

or add

shardimage/shardimage-php:"^1.0"

to your composer.json file and run update.

Quick start

Simple examples to use the package. For more details, please read our official documentation >>>

Configuring the Client

Configure the Client with information from our website to make connection with the 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
]);

Getting access datas

Your apiKey and apiSecret is available on Shardimage api page.

Access token can be created through Shardimage API, it requires a configured client with apiKey and 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>
}

Now we can configure an another Client for token image hosting:

use shardimage\shardimagephp\auth\Client;

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

Manage clouds with API

To upload and store images, cloud must to be created.

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

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

You can add features to your cloud to make it efficient and secure! To view the full list of our features, please check the documentation >>>

Notice: The deliverySecureUrl settings will work only, if you set up the client with the security information: image secret hash or access token/acces token secret.

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

Send to the API to create it.

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

If you already have clouds, you can list them:

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);

Manage images with API

To upload images to a cloud, or list from it, we need to use the ID of the cloud. The Shardimage PHP package is capable to upload images through single or multithreads, if you have big amount of pictures.

Single thread:

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

If everything goes alright, the $result variable will contain shardimage\shardimagephp\models\image\Image object with the uploaded image datas.

Multithread upload is very similar, we need to turn on the defer option before the upload. Turning it off will send the collected datas.

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

Unwanted pictures can be deleted from the system with two methods. Simple delete will delete one image by it's public ID and the cloud ID.

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

Other way is to delete images by their tags. In this case every images with the given tags will be deleted from the target cloud.

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

Using UploadBuilder

Using the builder class can make uploading easier by giving a developer friendly usage to build up upload parameters.

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());

Hosting images

Hosting the uploaded images with the packgate is basically generating their URL. Using the UrlService class you can build up remote image URLs also to serve them through the Shardimage. Practically, the Shardimage will store only the original uploaded image. Every modification, transformation, conversion will applied through URL rules or cloud settings. For further information, please check the documentation >>>

Example for generation URL for stored image:

$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>

Basic security hash will be added to the URL only if you set up the imageSecret in your client config.

Changelog

All notable changes to this project will be documented in the CHANGELOG file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

License

Read more >>

Links

• Shardimage
• Shardimage documentation
• Shardimage blog