<commit_before># Imbo - Image box
Imbo is an image "server" that can be used to add/get/delete images using a REST interface. There is also support for adding meta data to an image. The main idea behind Imbo is to have a place to store high quality original images and to use the REST interface to fetch variations of those images. Imbo will resize, rotate, crop (amongst other features) on the fly so you won't have to store all the different variations. Imbo comes with an administration dashboard that can be used to locate images. The dashboard will also support editing of meta data.

## Requirements
Imbo requires [PHP-5.3](http://php.net/), the [Imagine](https://github.com/avalanche123/imagine) image manipulation library, a running [MongoDB](http://www.mongodb.org/) and the [Mongo extension for PHP](http://pecl.php.net/package/mongo).

## Installation
Since this is a work in progress there is no automatic installation. Simply clone the repository or make your own fork. Automatic installation using [PEAR](http://pear.php.net/) will be provided later.

## REST API
Imbo uses a REST API to manage the images. Each image will be identified by a public key and an MD5 sum of the file itself and the original file extension. The latter will be referred to as &lt;image&gt; for the remainder of this document.

### GET /&lt;publicKey&gt;/&lt;image&gt;

Fetch the image identified by &lt;image&gt;. Read more about applying image transformations later on.

### GET /&lt;publicKey&gt;/&lt;image&gt;/meta

Get meta data related to the image identified by &lt;image&gt;. The meta data will be JSON encoded.

### GET /&lt;publicKey&gt;/images

Get information about the images stored in Imbo for the user with the public key &lt;publicKey&gt;. Supported query parameters are:

* `(int) page` The page number. Defaults to 1.
* `(int) num` Number of images pr. page. Defaults to 20.
* `(boolean) metadata` Wether or not to include metadata in the output. Defaults to false ('0'). Set to '1' to enable.
* `(int) from` Fetch images starting from this unix timestamp.
* `(int) to` Fetch images up until this timestamp.

Example:

* `GET /<publicKey>/images?page=1&num=30&metadata=1`

### PUT /&lt;publicKey&gt;/&lt;image&gt;

Place a new image on the server.

### POST /&lt;publicKey&gt;/&lt;image&gt;/meta

Edit the meta data attached to the image identified by &lt;image&gt;.

### DELETE /&lt;publicKey&gt;/&lt;image&gt;

Delete the image identified by &lt;image&gt; along with all meta data.

### DELETE /&lt;publicKey&gt;/&lt;image&gt;/meta

Delete the meta data attached to the image identified by &lt;image&gt;. The image is kept on the server.

### HEAD /&lt;publicKey&gt;/&lt;image&gt;

Fetch extra header information about a single image identified by &lt;image&gt;.

### HEAD /&lt;publicKey&gt;/&lt;image&gt;/meta

Fetches extra header information about the meta data attached to the image identified by &lt;image&gt;.

## Authentication
All write operations (PUT, POST and DELETE) requires authentication using an Hash-based Message Authentication Code (HMAC). The data Imbo uses when generating this code is:

* HTTP method (PUT, POST or DELETE)
* Resource identifier (for instance `<publicKey>/<image>` if your Imbo installation answers directly in the document root)
* Public key (random MD5 hash that exists both on the server and the client)
* GMT timestamp (YYYY-MM-DDTHH:MMZ, for instance: 2011-02-01T14:33Z)

These elements are concatenated in the above order and a hash is generated using a private key and the sha256 algorithm. The following snippet shows how this can be done using PHP:

    <?php
    $publicKey  = '<some random MD5 hash>';
    $privateKey = '<some other random MD5 hash>';
    $method     = 'DELETE';
    $resource   = 'b8533858299b04af3afc9a3713e69358.jpeg/meta'
    $timestamp  = gmdate('Y-m-d\TH:i\Z');

    $data       = $method . $resource . $publicKey . $timestamp;

    $hash       = hash_hmac('sha256', $data, $privateKey, true);
    $signature  = base64_encode($hash);
    $url        = sprintf('http://example.com/%s/%s?signature=%s&timestamp=%s',
                          $publicKey,
                          $resource,
                          rawurlencode($signature),
                          rawurlencode($timestamp));

The above code will generate a signature that must be sent along the request using the `signature` query parameter. The timestamp used must also be provided using the `timestamp` query parameter so that the signature can be regenerated server-side. A generated signature is only valid for 5 minutes. Both the signature and the timestamp must be url encoded (by using for instance PHPs [rawurlencode](http://php.net/rawurlencode).

The public and private key pair used by clients must be specified in the server configuration. More information on the configuration file can be found later in this document.

## Image transformations
Imbo supports some image transformations out of the box using the [Imagine](https://github.com/avalanche123/Imagine/) image manipulation library.

Transformations are made using the `t[]` query parameter. This GET parameter should be used as an array so that multiple transformations can be made. The transformations are made in the order they are specified in the url.

### resize
This transformation will resize the image. Two parameters are supported and at least one of them must be supplied to apply this transformation.

* `(int) width` The width of the resulting image in pixels. If not specified the width will be calculated using the same ratio as the original image.<commit_msg>Updated README with the new urls<commit_after># Imbo - Image box
Imbo is an image "server" that can be used to add/get/delete images using a REST interface. There is also support for adding meta data to an image. The main idea behind Imbo is to have a place to store high quality original images and to use the REST interface to fetch variations of those images. Imbo will resize, rotate, crop (amongst other features) on the fly so you won't have to store all the different variations. Imbo comes with an administration dashboard that can be used to locate images. The dashboard will also support editing of meta data.

## Requirements
Imbo requires [PHP-5.3](http://php.net/), the [Imagine](https://github.com/avalanche123/imagine) image manipulation library, a running [MongoDB](http://www.mongodb.org/) and the [Mongo extension for PHP](http://pecl.php.net/package/mongo).

## Installation
Since this is a work in progress there is no automatic installation. Simply clone the repository or make your own fork. Automatic installation using [PEAR](http://pear.php.net/) will be provided later.

## REST API
Imbo uses a REST API to manage the images. Each image will be identified by a public key and an MD5 sum of the file itself and the original file extension. The latter will be referred to as &lt;image&gt; for the remainder of this document.

### GET /users/&lt;publicKey&gt;/images/&lt;image&gt;

Fetch the image identified by &lt;image&gt;. Read more about applying image transformations later on.

### GET /users/&lt;publicKey&gt;/images/&lt;image&gt;/meta

Get meta data related to the image identified by &lt;image&gt;. The meta data will be JSON encoded.

### GET /users/&lt;publicKey&gt;/images

Get information about the images stored in Imbo for the user with the public key &lt;publicKey&gt;. Supported query parameters are:

* `(int) page` The page number. Defaults to 1.
* `(int) num` Number of images pr. page. Defaults to 20.
* `(boolean) metadata` Wether or not to include metadata in the output. Defaults to false ('0'). Set to '1' to enable.
* `(int) from` Fetch images starting from this unix timestamp.
* `(int) to` Fetch images up until this timestamp.

Example:

* `GET /users/<publicKey>/images?page=1&num=30&metadata=1`

### PUT /users/&lt;publicKey&gt;/images/&lt;image&gt;

Place a new image on the server.

### POST /users/&lt;publicKey&gt;/images/&lt;image&gt;/meta

Edit the meta data attached to the image identified by &lt;image&gt;.

### DELETE /users/&lt;publicKey&gt;/images/&lt;image&gt;

Delete the image identified by &lt;image&gt; along with all meta data.

### DELETE /users/&lt;publicKey&gt;/images/&lt;image&gt;/meta

Delete the meta data attached to the image identified by &lt;image&gt;. The image is kept on the server.

### HEAD /users/&lt;publicKey&gt;/images/&lt;image&gt;

Fetch extra header information about a single image identified by &lt;image&gt;.

### HEAD /users/&lt;publicKey&gt;/images/&lt;image&gt;/meta

Fetches extra header information about the meta data attached to the image identified by &lt;image&gt;.

## Authentication
All write operations (PUT, POST and DELETE) requires authentication using an Hash-based Message Authentication Code (HMAC). The data Imbo uses when generating this code is:

* HTTP method (PUT, POST or DELETE)
* Resource identifier (for instance `<publicKey>/<image>` if your Imbo installation answers directly in the document root)
* Public key (random MD5 hash that exists both on the server and the client)
* GMT timestamp (YYYY-MM-DDTHH:MMZ, for instance: 2011-02-01T14:33Z)

These elements are concatenated in the above order and a hash is generated using a private key and the sha256 algorithm. The following snippet shows how this can be done using PHP:

    <?php
    $publicKey  = '<some random MD5 hash>';
    $privateKey = '<some other random MD5 hash>';
    $method     = 'DELETE';
    $resource   = 'b8533858299b04af3afc9a3713e69358.jpeg/meta'
    $timestamp  = gmdate('Y-m-d\TH:i\Z');

    $data       = $method . $resource . $publicKey . $timestamp;

    $hash       = hash_hmac('sha256', $data, $privateKey, true);
    $signature  = base64_encode($hash);
    $url        = sprintf('http://example.com/users/%s/images/%s?signature=%s&timestamp=%s',
                          $publicKey,
                          $resource,
                          rawurlencode($signature),
                          rawurlencode($timestamp));

The above code will generate a signature that must be sent along the request using the `signature` query parameter. The timestamp used must also be provided using the `timestamp` query parameter so that the signature can be regenerated server-side. A generated signature is only valid for 5 minutes. Both the signature and the timestamp must be url encoded (by using for instance PHPs [rawurlencode](http://php.net/rawurlencode).

The public and private key pair used by clients must be specified in the server configuration. More information on the configuration file can be found later in this document.

## Image transformations
Imbo supports some image transformations out of the box using the [Imagine](https://github.com/avalanche123/Imagine/) image manipulation library.

Transformations are made using the `t[]` query parameter. This GET parameter should be used as an array so that multiple transformations can be made. The transformations are made in the order they are specified in the url.

### resize
This transformation will resize the image. Two parameters are supported and at least one of them must be supplied to apply this transformation.

* `(int) width` The width of the resulting image in pixels. If not specified the width will be calculated using the same ratio as the original image.
{'fraction_non_alphanumeric': 0.09026798307475317, 'fraction_numerical': 0.011459802538787024, 'mean_word_length': 4.04670818505338, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 13, 'https://': 4, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '603149', 'n_tokens_mistral': 3217, 'n_tokens_neox': 3076, 'n_words': 1462}