class Image extends Base (View source)

Image client for the rokka.io service.

All code examples assume you already have a Rokka Image Client in $client with:

$client = \Rokka\Client\Factory::getImageClient('testorganization', 'apiKey');

Constants

DEFAULT_API_BASE_URL

DEFAULT_API_VERSION

API_KEY_HEADER

API_VERSION_HEADER

SOURCEIMAGE_RESOURCE

DYNAMIC_META_RESOURCE

USER_META_RESOURCE

STACK_RESOURCE

OPERATIONS_RESOURCE

Properties

protected ClientInterface $client

Client to access Rokka.

from  Base
protected string|null $defaultOrganization

Default organization.

from  Base

Methods

__construct(ClientInterface $client, string|null $defaultOrganization, string $apiKey)

Constructor.

setCredentials(string $key)

Set the credentials.

from  Base
ResponseInterface
call(string $method, string $path, array $options = [], bool $needsCredentials = true)

Call the API rokka endpoint.

from  Base
string
getOrganizationName(string|null $organization = null)

Return the organization or the default if empty.

from  Base
uploadSourceImage(string $contents, string $fileName, string $organization = '', array|null $options = null)

Upload a source image.

uploadSourceImageByUrl(string $url, string $organization = '', array|null $options = null)

Upload a source image.

bool
deleteSourceImage(string $hash, string $organization = '')

Delete a source image.

bool
restoreSourceImage(string $hash, string $organization = '')

Restore a source image.

bool
copySourceImage(string $hash, string $destinationOrg, bool $overwrite = true, string $sourceOrg = '')

Copy a source image to another org.

array
copySourceImages(array $hashes, string $destinationOrg, bool $overwrite = true, string $sourceOrg = '')

Copy multiple sources image to another org.

bool
deleteSourceImagesWithBinaryHash(string $binaryHash, string $organization = '')

Delete source images by binaryhash.

searchSourceImages(array $search = [], array $sorts = [], int|null $limit = null, int|string|null $offset = null, string $organization = '')

Search and list source images.

listSourceImages(null|int $limit = null, null|int|string $offset = null, string $organization = '') deprecated

List source images.

getSourceImage(string $hash, string $organization = '')

Load a source image's metadata from Rokka.

getSourceImagesWithBinaryHash(string $binaryHash, string $organization = '')

Loads source images metadata from Rokka by binaryhash.

string
getSourceImageContents(string $hash, string $organization = '')

Get a source image's binary contents from Rokka.

listOperations()

List operations.

createStack(string $stackName, array $stackOperations, string $organization = '', array $stackOptions = [], bool $overwrite = false) deprecated

Create a stack.

saveStack(Stack $stack, array $requestConfig = [])

Save a stack on rokka.

listStacks(null|int $limit = null, null|int $offset = null, string $organization = '')

List stacks.

getStack(string $stackName, string $organization = '')

Return a stack.

bool
deleteStack(string $stackName, string $organization = '')

Delete a stack.

string|false
setDynamicMetadata(DynamicMetadataInterface|array $dynamicMetadata, string $hash, string $organization = '', array $options = [])

Add the given DynamicMetadata to a SourceImage.

string|false
deleteDynamicMetadata(string $dynamicMetadataName, string $hash, string $organization = '', array $options = [])

Delete the given DynamicMetadata from a SourceImage.

bool
setUserMetadataField(string $field, string $value, string $hash, string $organization = '')

Add (or update) the given user-metadata field to the image.

bool
addUserMetadata(array $fields, string $hash, string $organization = '')

Add the given fields to the user-metadata of the image.

bool
setUserMetadata(array $fields, string $hash, string $organization = '')

Set the given fields as the user-metadata of the image.

bool
deleteUserMetadata(string $hash, string $organization = '')

Delete the user-metadata from the given image.

bool
deleteUserMetadataField(string $field, string $hash, string $organization = '')

Delete the given field from the user-metadata of the image.

bool
deleteUserMetadataFields(array $fields, string $hash, string $organization = '')

Delete the given fields from the user-metadata of the image.

UriInterface
getSourceImageUri(string $hash, string|StackUri $stack, string $format = 'jpg', string $name = null, string $organization = null)

Returns url for accessing the image.

string|false
extractHashFromLocationHeader(array $headers)

Helper function to extract from a Location header the image hash, only the first Location is used.

Details

__construct(ClientInterface $client, string|null $defaultOrganization, string $apiKey)

Constructor.

Parameters

ClientInterface $client

Client instance

string|null $defaultOrganization
string $apiKey

API key

setCredentials(string $key)

Set the credentials.

Parameters

string $key

API key

protected ResponseInterface call(string $method, string $path, array $options = [], bool $needsCredentials = true)

Call the API rokka endpoint.

Parameters

string $method

HTTP method to use

string $path

Path on the API

array $options

Request options

bool $needsCredentials

True if credentials are needed

Return Value

ResponseInterface

Exceptions

GuzzleException

protected string getOrganizationName(string|null $organization = null)

Return the organization or the default if empty.

Parameters

string|null $organization Organization

Return Value

string

Exceptions

RuntimeException

SourceImageCollection uploadSourceImage(string $contents, string $fileName, string $organization = '', array|null $options = null)

Upload a source image.

Parameters

string $contents

Image contents

string $fileName

Image file name

string $organization

Optional organization

array|null $options

Options for creating the image (like meta_user and meta_dynamic)

Return Value

SourceImageCollection

If no image contents are provided to be uploaded

Exceptions

GuzzleException
RuntimeException

SourceImageCollection uploadSourceImageByUrl(string $url, string $organization = '', array|null $options = null)

Upload a source image.

Parameters

string $url

url to a remote image

string $organization

Optional organization

array|null $options

Options for creating the image (like meta_user and meta_dynamic)

Return Value

SourceImageCollection

If no image contents are provided to be uploaded

Exceptions

GuzzleException
RuntimeException

bool deleteSourceImage(string $hash, string $organization = '')

Delete a source image.

Parameters

string $hash

Hash of the image

string $organization

Optional organization name

Return Value

bool

True if successful, false if image not found

Exceptions

GuzzleException
Exception

bool restoreSourceImage(string $hash, string $organization = '')

Restore a source image.

Parameters

string $hash

Hash of the image

string $organization

Optional organization name

Return Value

bool

True if successful, false if image not found

Exceptions

GuzzleException

bool copySourceImage(string $hash, string $destinationOrg, bool $overwrite = true, string $sourceOrg = '')

Copy a source image to another org.

Needs read permissions on the source organization and write permissions on the write organization.

Parameters

string $hash

Hash of the image

string $destinationOrg

The destination organization

bool $overwrite

If an existing image should be overwritten

string $sourceOrg

Optional source organization name

Return Value

bool

True if successful, false if source image not found

Exceptions

GuzzleException

array copySourceImages(array $hashes, string $destinationOrg, bool $overwrite = true, string $sourceOrg = '')

Copy multiple sources image to another org.

Needs read permissions on the source organization and write permissions on the write organization.

Parameters

array $hashes

Hashes of the images as array (max. 100)

string $destinationOrg

The destination organization

bool $overwrite

If an existing image should be overwritten

string $sourceOrg

Optional source organization name

Return Value

array

An array in the form of ['existing' => [...], 'created' => [..]] with all the hashes in it

Exceptions

GuzzleException
RuntimeException

bool deleteSourceImagesWithBinaryHash(string $binaryHash, string $organization = '')

Delete source images by binaryhash.

Since the same binaryhash can have different images in rokka, this may delete more than one picture.

Parameters

string $binaryHash

Hash of the image

string $organization

Optional organization name

Return Value

bool

True if successful, false if image not found

Exceptions

GuzzleException
Exception

SourceImageCollection searchSourceImages(array $search = [], array $sorts = [], int|null $limit = null, int|string|null $offset = null, string $organization = '')

Search and list source images.

Sort direction can either be: "asc", "desc" (or the boolean TRUE value, treated as "asc")

Parameters

array $search

The search query, as an associative array "field => value"

array $sorts

The sorting parameters, as an associative array "field => sort-direction"

int|null $limit

Optional limit

int|string|null $offset

Optional offset, either integer or the "Cursor" value

string $organization

Optional organization name

Return Value

SourceImageCollection

Exceptions

GuzzleException
RuntimeException

SourceImageCollection listSourceImages(null|int $limit = null, null|int|string $offset = null, string $organization = '') deprecated

deprecated 2.0.0 Use Image::searchSourceImages()

List source images.

Parameters

null|int $limit

Optional limit

null|int|string $offset

Optional offset, either integer or the "Cursor" value

string $organization

Optional organization name

Return Value

SourceImageCollection

Exceptions

GuzzleException
RuntimeException

See also

Image::searchSourceImages

SourceImage getSourceImage(string $hash, string $organization = '')

Load a source image's metadata from Rokka.

Parameters

string $hash

Hash of the image

string $organization

Optional organization name

Return Value

SourceImage

Exceptions

GuzzleException
RuntimeException

SourceImageCollection getSourceImagesWithBinaryHash(string $binaryHash, string $organization = '')

Loads source images metadata from Rokka by binaryhash.

Since the same binaryhash can have different images in rokka, this may return more than one picture.

Parameters

string $binaryHash

Hash of the image

string $organization

Optional organization name

Return Value

SourceImageCollection

Exceptions

GuzzleException
RuntimeException

string getSourceImageContents(string $hash, string $organization = '')

Get a source image's binary contents from Rokka.

Parameters

string $hash

Hash of the image

string $organization

Optional organization name

Return Value

string

Exceptions

GuzzleException
RuntimeException

OperationCollection listOperations()

List operations.

Return Value

OperationCollection

Exceptions

GuzzleException
RuntimeException

Stack createStack(string $stackName, array $stackOperations, string $organization = '', array $stackOptions = [], bool $overwrite = false) deprecated

deprecated 2.0.0 Use Image::saveStack() instead

Create a stack.

Parameters

string $stackName

Name of the stack

array $stackOperations

Stack operations

string $organization

Optional organization name

array $stackOptions

Stack options

bool $overwrite

If an existing stack should be overwritten

Return Value

Stack

Exceptions

GuzzleException
RuntimeException

See also

Image::saveStack

Stack saveStack(Stack $stack, array $requestConfig = [])

Since: 1.1.0

Save a stack on rokka.

Example:

$stack = new Stack(null, 'teststack');
$stack->addStackOperation(new StackOperation('resize', ['width' => 200, 'height' => 200]));
$stack->addStackOperation(new StackOperation('rotate', ['angle' => 45]));
$stack->setStackOptions(['jpg.quality' => 80]);
$requestConfig = ['overwrite' => true];
$stack = $client->saveStack($stack, $requestConfig);
echo 'Created stack ' . $stack->getName() . PHP_EOL;

The only requestConfig option currently can be ['overwrite' => true|false] (false is the default)

Parameters

Stack $stack

the Stack object to be saved

array $requestConfig

options for the request

Return Value

Stack

Exceptions

GuzzleException
LogicException
RuntimeException

StackCollection listStacks(null|int $limit = null, null|int $offset = null, string $organization = '')

List stacks.

use Rokka\Client\Core\Stack;
$client = \Rokka\Client\Factory::getImageClient('testorganization', 'apiKey');
$stacks = $client->listStacks();
foreach ($stacks as $stack) {
  echo 'Stack ' . $stack->getName() . PHP_EOL;
}

Parameters

null|int $limit

Optional limit

null|int $offset

Optional offset

string $organization

Optional organization name

Return Value

StackCollection

Exceptions

GuzzleException
RuntimeException

Stack getStack(string $stackName, string $organization = '')

Return a stack.

Parameters

string $stackName

Stack name

string $organization

Optional organization name

Return Value

Stack

Exceptions

GuzzleException
RuntimeException

bool deleteStack(string $stackName, string $organization = '')

Delete a stack.

Parameters

string $stackName

Delete the stack

string $organization

Optional organization name

Return Value

bool

True if successful

Exceptions

GuzzleException

string|false setDynamicMetadata(DynamicMetadataInterface|array $dynamicMetadata, string $hash, string $organization = '', array $options = [])

Add the given DynamicMetadata to a SourceImage.

Returns the new Hash for the SourceImage, it could be the same as the input one if the operation did not change it.

The only option currently can be ['deletePrevious' => true]

which deletes the previous image from rokka (but not the binary, since that's still used) If not set, the original image is kept in rokka.

Parameters

DynamicMetadataInterface|array $dynamicMetadata

A Dynamic Metadata object, an array with all the needed info. Or an array with more than one of those.

string $hash

The Image hash

string $organization

Optional organization name

array $options

Optional options

Return Value

string|false

Exceptions

GuzzleException
RuntimeException

string|false deleteDynamicMetadata(string $dynamicMetadataName, string $hash, string $organization = '', array $options = [])

Delete the given DynamicMetadata from a SourceImage.

Returns the new Hash for the SourceImage, it could be the same as the input one if the operation did not change it.

The only option currently can be ['deletePrevious' => true] which deletes the previous image from rokka (but not the binary, since that's still used) If not set, the original image is kept in rokka.

Parameters

string $dynamicMetadataName

The DynamicMetadata name

string $hash

The Image hash

string $organization

Optional organization name

array $options

Optional options

Return Value

string|false

Exceptions

GuzzleException
RuntimeException

bool setUserMetadataField(string $field, string $value, string $hash, string $organization = '')

Add (or update) the given user-metadata field to the image.

Parameters

string $field

The field name

string $value

The field value

string $hash

The image hash

string $organization

The organization name

Return Value

bool

Exceptions

GuzzleException

bool addUserMetadata(array $fields, string $hash, string $organization = '')

Add the given fields to the user-metadata of the image.

Parameters

array $fields

An associative array of "field-name => value"

string $hash

The image hash

string $organization

The organization name

Return Value

bool

Exceptions

GuzzleException

bool setUserMetadata(array $fields, string $hash, string $organization = '')

Set the given fields as the user-metadata of the image.

Parameters

array $fields

An associative array of "field-name => value"

string $hash

The image hash

string $organization

The organization name

Return Value

bool

Exceptions

GuzzleException

bool deleteUserMetadata(string $hash, string $organization = '')

Delete the user-metadata from the given image.

Parameters

string $hash

The image hash

string $organization

The organization name

Return Value

bool

Exceptions

GuzzleException

bool deleteUserMetadataField(string $field, string $hash, string $organization = '')

Delete the given field from the user-metadata of the image.

Parameters

string $field

The field name

string $hash

The image hash

string $organization

The organization name

Return Value

bool

Exceptions

GuzzleException

bool deleteUserMetadataFields(array $fields, string $hash, string $organization = '')

Delete the given fields from the user-metadata of the image.

Parameters

array $fields

The fields name

string $hash

The image hash

string $organization

The organization name

Return Value

bool

Exceptions

GuzzleException

UriInterface getSourceImageUri(string $hash, string|StackUri $stack, string $format = 'jpg', string $name = null, string $organization = null)

Returns url for accessing the image.

Parameters

string $hash

Identifier Hash

string|StackUri $stack

Stack to apply (name or StackUri object)

string $format

Image format for output [jpg|png|gif]

string $name

Optional image name for SEO purposes

string $organization

Optional organization name (if different from default in client)

Return Value

UriInterface

Exceptions

RuntimeException

protected string|false extractHashFromLocationHeader(array $headers)

Helper function to extract from a Location header the image hash, only the first Location is used.

Parameters

array $headers

The collection of Location headers

Return Value

string|false