ImboClient - PHP

This is the official PHP-based client for Imbo servers.


The client requires PHP >= 5.3.3.


ImboClient can be installed using Composer by requiring imbo/imboclient in your composer.json file, or by running the following commands:

curl -s | php
php composer.phar create-project imbo/imboclient [<dir>] [<version>]

Available versions can be located at packagist.


Below you will find documentation covering most features of the client.

Instantiating the client

This can be achieved in two different ways:

  1. Use the factory:
$client = ImboClient\ImboClient::factory(array(
    'serverUrls' => array(''),
    'publicKey' => 'user',
    'privateKey' => 'private key',
  1. Use the constructor:
$client = new ImboClient\ImboClient('', array(
    'publicKey' => 'user',
    'privateKey' => 'private key',

The main difference is that the first argument to the factory method requires you to specify the host name(s) of the Imbo server(s) as an array, while the constructor requires you to pass a string. If you want to use the example number 2 above, and still want to use multiple host names you can use the setServerUrls method:


If you use multiple URLs when instantiating the client it will choose different image URLs based on the image identifier and the number of available host names. If you have a site which includes a lot of <img> tags against an Imbo server, using multiple hosts might speed up the loading time for your users. If you don’t change the amount of server URLs the client will always pick the same host name given the same image identifier.

Error handling

Most methods will throw a Guzzle\Common\Exception\GuzzleException exception if the server responds with an error (as in HTTP 4** or 5**). Some methods might also throw an InvalidArgumentException exception of the provided parameter to a method is invalid (for instance if you try to add an image and provide a local path to a file that does not exist). Remember to use try/catch if you want to handle these errors gracefully.

Get server status

If you want to get the server status, you can use the getServerStatus method:

$status = $client->getServerStatus();

The $status value above can be used as an associative array, and includes the following elements:

(boolean) database
Whether or not the configured database works as expected on the server.
(boolean) storage
Whether or not the configured storage works as expected on the server.
(int) status
The HTTP status code.
(string) message
The HTTP response reason phrase.

Get server statistics

If you have access to the server statistics and want to fetch these, you can use the getServerStats method:

$stats = $client->getServerStats();

The return value from this method can be used as an associative array, and includes the following elements:

(array) users

An array of users where the keys are user names (public keys) and values are arrays with the following elements:

  • (int) numImages: Number of images owned by this user
  • (int) numBytes: Number of bytes stored by this user
(array) total

An array with aggregated values. The array includes the following elements:

  • (int) numImages: The number of images on the server
  • (int) numUsers: The number of users on the server
  • (int) numBytes: The number of bytes stored on the server
(array) custom
If the server has configured any custom statistics, these are available in this element.

Get user info

Get some information about the user configured with the client:

$info = $client->getUserInfo();

The value returned from the getUserInfo method includes the following elements:

(string) publicKey
The public key of the user (the same as the one used when instantiating the client).
(int) numImages
The number of images owned by the user.
(DateTime) lastModified
A DateTime instance representing when the user last modified any data on the server.

Add an image

The first thing you might want to do is to start adding images. This can be done in several ways:

  1. Add an image from a local path:
$response = $client->addImage('/path/to/image.jpg');
  1. Add an image from a URL:
$response = $client->addImageFromUrl('');
  1. Add an in-memory image:
$response = $client->addImageFromString(file_get_contents('/path/to/image.jpg'));

The $response returned from these methods holds the resulting image identifier of the image, and can be fetched by using the response as an associative array:

echo 'Image added, identifier: ' . $response['imageIdentifier'];

This is the identifier you will use when generating URLs to the image later on. The response also has some other information that you might find useful:

(string) imageIdentifier
As mentioned above, the ID of the added image.
(int) width
The width of the added image.
(int) height
The height of the added image.
(string) extension
The extension of the added image.
(int) status
The HTTP status of the response from the server. Should be 200 or 201.

The width and height can differ from the original image if the server has added event listeners that might change incoming images. Some changes that might occur is auto rotating based on EXIF-data embedded into the image, and if a max image size is being enforced by the server.

Get image properties

You can fetch properties of the image by using the getImageProperties method, specifying the image identifier of an image:

$properties = $client->getImageProperties('image identifier');

The return value can be used as an associative array, and contains the following elements:

(int) width
The width of the image in pixels.
(int) height
The height of the image in pixels.
(int) filesize
The file size of the image in bytes.
(string) extension
The extension of the image.
(string) mimetype
The mime type of the image.

Delete an image

If you want to delete an image from the server, you can use the deleteImage method:

$response = $client->deleteImage('identifier');

where 'identifier' is the value of the imageIdentifier key of the response returned when adding images.

Check for the existence of images on the server

If you want to see if a local image exists on the server, use the imageExists($path) method:

$path = '/path/to/image.jpg';
$exists = $client->imageExists($path);

echo '"' . $path . '" ' . ($exists ? 'exists' : 'does not exist') . ' on the server.';

You can also check for the existence of an image identifier on the server by using the imageIdentifierExists($imageIdentifier) method.

Get the number of added images

If you want to fetch the number of images owned by the current user you can use the getNumImages methods:

echo 'The user "' . $client->getPublicKey() . '" has ' . $client->getNumImages() . ' images.';

Get the binary image data

If you want to fetch the binary data of an image as a string you can use getImageData($imageIdentifier). If you have an instance of an image URL you can use the getImageDataFromUrl(ImboClient\Http\ImageUrl $imageUrl) method:

$imageData = $client->getImageData($imageIdentifier);

// or

$imageData = $client->getImagedataFromUrl($client->getImageUrl($imageIdentifier)->thumbnail()->border());

You can read more about the image URLs in the Imbo URLs section.

Search for images

The client also let’s you search for images on the server. This is done via the getImages method:

$collection = $client->getImages();

echo '<h1>Images on the server:</h1>';
echo '<ul>';

foreach ($collection['images'] as $image) {
    echo '<li>' . $image['imageIdentifier'] . '</li>';

echo '</ul>';

The $collection variable returned from the getImages methods has two elements: search and images. search is an array related to pagination and holds information about the images returned by your query:

(int) hits
The number of hits from your query.
(int) page
The current page.
(int) limit
Limit the number of images per page.
(int) count
The number of images currently on the page.

and the images element is a traversable where each element represents an image. Each image is an associative array which includes the following elements:

  • added
  • updated
  • checksum
  • originalChecksum
  • extension
  • size
  • width
  • height
  • mime
  • imageIdentifier
  • publicKey
  • metadata (only if the query explicitly enabled metadata in the response, which is off by default).

Some of these elements might not be available if the query excludes some fields (more on that below).

The getImages method can also take a parameter which specifies a query to execute. The parameter is an instance of the ImboClient\ImagesQuery class. This class has a set of methods that can be used to customize your query. All methods can be chained when used with a parameter (when setting a value). If you skip the parameter, the methods will return the current value instead:

page($page = null)
Set or get the page value. Defaults to 1.
limit($limit = null)
Set or get the limit value. Defaults to 20.
metadata($metadata = null)
Set to true to return metadata attached to the images. Defaults to false. Setting this to true will make the client include the metadata element mentioned above in the images in the collection.
from($from = null)
Specify a Unix timestamp which represents the oldest image you want returned in the collection. Defaults to null.
to($to = null)
Specify a Unix timestamp which represents the newest image you want returned in the collection. Defaults to null.
fields(array $fields = null)

Specify which fields should be available per image in the images element of the response. Defaults to null (all fields). The fields to include are mentioned above.


If you want to include metadata in the response, remember to include metadata in the set of fields, if you specify custom fields.

sort(array $sort = null)
Specify which field(s) to sort by. Defaults to date:desc. All fields mentioned above can be sorted by, and they all support asc and desc. If you don’t specify a sort order asc will be used.
ids(array $ids = null)
Only include these image identifiers in the collection. Defaults to null.
checksums(array $checksums = null)
Only include these MD5 checksums in the collection. Defaults to null.
originalChecksums(array $checksums = null)
Only include these original MD5 checksums in the collection. Defaults to null.

Here are some examples of how to use the query object:

  1. Fetch (at most) 10 images added within the last 24 hours, sorted by the image byte size (ascending) and then the width of the image (descending):
$current = time();
$query = new ImboClient\ImagesQuery();
$query->limit(10)->from($current - 3600 * 24)->sort(array('size', 'width:desc'));

$collection = $client->getImages($query);
  1. Include metadata in the response:
$query = new ImboClient\ImagesQuery();

$collection = $client->getImages($query);
  1. Only fetch the width and height fields on a set of images:
$query = new ImboClient\ImagesQuery();
$query->ids(array('id1', 'id2', 'id3'))->fields(array('width', 'height'));

$collection = $client->getImages($query);

If you want to return metadata, and happen to specify custom fields you will need to explicitly add the metadata field. If you don’t use the fields method this is not necessary:

$query->metadata(true)->fields(array('size')); // Does include the metadata field
$query->metadata(true)->fields(array('size', 'metadata')); // Includes the size and metadata fields
$query->metadata(true); // Includes all fields, including metadata
$query->metadata(false); // Exclude the metadata field (default behaviour)

Get metadata

Images in Imbo can have metadata attached to them. If you want to fetch this data you can use the getMetadata method:

$metadata = $client->getMetadata('image identifier');

echo '<dl>';

foreach ($metadata as $key => $value) {
    echo '<dt>' . $key . '</dt>';
    echo '<dd>' . $value . '</dd>';

echo '</dl>';

Update metadata

If you have added an image and want to edit its metadata you can use the editMetadata method:

$metadata = $client->editMetadata('image identifier', array(
    'key' => 'value',
    'other key' => 'other value',

This method will partially update existing metadata, and the response contains all metadata attached to the image.

Replace metadata

If you want to replace all existing metadata with something else you can use the replaceMetadata method:

$metadata = $client->replaceMetadata('image identifier', array(
    'key' => 'value',
    'other key' => 'other value',

This will first remove existing (if any) metadata, and add the metadata specified as the second parameter. The response contains the metadata of the image, in this case the same as the data being sent to the server.

Delete metadata

If you want to remove all metadata attached to an image you can use the deleteMetadata method:

$metadata = $client->deleteMetadata('image identifier');

The response is the existing metadata, which in this case is an empty object.

Generate short image URL

To be able to generate short image URLs you can use the generateShortUrl method, and simply specify an instance of the image URL you want to shorten:

// Create an image URL with some optional transformations
$imageUrl = $client->getImageUrl('image identifier')->thumbnail()->desaturate()->jpg();

// Pass the image URL instance to the generateShortUrl method
$response = $client->generateShortUrl($imageUrl);

echo 'Short URL ID: ' . $response['id'];

The generated ID can be used with the global short URL resource in Imbo.

Imbo URLs

Imbo uses access tokens in the URLs to prevent DoS attacks, and the client includes functionality that does this automatically:

Fetch a URL to the status endpoint.
Fetch a URL to the stats endpoint.
Fetch a URL to the user information of the current user (specified by setting the correct public key when instantiating the client)``.
Fetch a URL to the images endpoint.
Fetch a URL to a specific image.
Fetch a URL to the metadata of a specific image.

All these methods return instances of different classes, and all can be used in string context to get the URL with the access token added. The instance returned from the getImageUrl is somewhat special since it will let you chain a set of transformations before generating the URL as a string:

$imageUrl = $client->getImageUrl('image identifier');

echo '<img src="' . $imageUrl . '">';

The available transformation methods are:

  • autoRotate()
  • border($color = '000000', $width = 1, $height = 1, $mode = 'outbound')
  • canvas($width, $height, $mode = null, $x = null, $y = null, $bg = null)
  • compress($level = 75)
  • crop($x, $y, $width, $height, $mode)
  • desaturate()
  • flipHorizontally()
  • flipVertically()
  • histogram($scale = null, $ratio = null, $red = null, $green = null, $blue = null)
  • maxSize($maxWidth = null, $maxHeight = null)
  • modulate($brightness = null, $saturation = null, $hue = null)
  • progressive()
  • resize($width = null, $height = null)
  • rotate($angle, $bg = '000000')
  • sepia($threshold = 80)
  • strip()
  • thumbnail($width = 50, $height = 50, $fit = 'outbound')
  • transpose()
  • transverse()
  • watermark($img = null, $width = null, $height = null, $position = 'top-left', $x = 0, $y = 0)

Please refer to the server documentation for details about the image transformations.

There are also some other methods available:


Can be used to add a custom transformation (that needs to be available on the server):

$url->addTransformation('foobar'); // results in t[]=foobar being added to the URL

Convert the image to one of the supported types:

  • jpg
  • gif
  • png
Proxies to convert('gif').
Proxies to convert('jpg').
Proxies to convert('png').
Removes all transformations added to the URL instance.

The methods related to the image type (convert and the proxy methods) can be added anywhere in the chain. Otherwise all transformations will be applied to the image in the same order as they appear in the chain.

Migrating from ImboClient < 1.0.0

ImboClient’s API changed somewhat with the release of version 1.0.0. This section should help you migrate from an older version of the client.

Instantiating the client

From version 1.0.0 ImboClient comes with a factory that should be used to instantiate the client:

$client = ImboClient\ImboClient::factory(array(
    'serverUrls' => array(''),
    'publicKey' => 'user',
    'privateKey' => 'private key',

More examples on how to instantiate the client are available in the Instantiating the client section.

Response objects

All methods now return response objects that can be used as arrays, whereas the old client returned objects with accessor methods for the image identifier and more. Below is an example that shows the difference:

// New client
$response = $client->addImage('/path/to/image.jpg');
echo "Image identifier: " . $response['imageIdentifier'];

// Old client
$response = $client->addImage('/path/to/image.jpg');
echo "Image identifier: " . $response->getImageIdentifier();

Translating old URLs

If you for some reason have stored complete Imbo URLs (including access tokens), which you should really try to avoid, you might want to re-generate these if you get some “incorrect access token” errors from the server. This can be done in the following fashion:

// Create an instance of an image URL, using the old URL with the faulty access token and the
// current private key of the user as input
$url = ImboClient\Http\ImageUrl::factory(
    'http://imbo/users/user/images/image?t[]=resize:width=100&accessToken=<incorrect token>',
    'your private key'

// Remove the incorrect access token from the query parameters

// Convert the URL to a string to get the new URL, including the correct access token
echo "New URL: " . $url;


All exceptions thrown by the client related to response errors from the server implement the Guzzle\Common\Exception\GuzzleException interface. Earlier versions of the threw ImboClient\Exception\ServerException exceptions. This exception no longer exists.

The client can also throw InvalidArgumentException on some occasions if you provide invalid arguments to some methods, whereas the old client threw either ImboClient\Exception\InvalidArgumentException or ImboClient\Exception\RuntimeException. None of these two exceptions exist anymore.