README

PHP bindings for SoftLayer Object Storage

Install

Unzip the files and make sure to include lib/ObjectStorage/Util.php once somewhere in your script

Requirements

* Mandatory
    * PHP version > 5.2
	* PHP OpenSSL extension (if your PHP is compiled by your self, make sure compile it with: --with-openssl configure)
* Optional
    * Zend Framework (for HTTP Client)
    * CURL

Documents

Documents are generated by PHPDocumentor. See docs directory for details.

Tests

The test cases are run using phpunit version PHPUnit 3.5.13 To run a test, provide your object storage credentials in test/BaseTest.php file.

Examples

Configuring Object Storage

// If you want to cache ObjectStorage authentication token:
$tokenStore = ObjectStorage_TokenStore::factory('file', array('ttl' => 3600, 'path' => '/tmp/objectStorage'));
ObjectStorage::setTokenStore($tokenStore);

// If no adapter option is provided, CURL will be used.
$options = array('adapter' => ObjectStorage_Http_Client::SOCKET, 'timeout' => 10);
 $host = 'https://dal05.objectstorage.softlayer.net'; // the SoftLayer Object Storage API host
 $username = 'SLOS778231112-1:3241234'; // user name and password is display at https://manage.softlayer.com/ObjectStorage/index
 $password = 'ksd83ksd8ksdfhx823ks8cksew8slsdi82ls8xlsd8l';

$objectStorage = new ObjectStorage($host, $username, $password, $options);

Basic CRUD

$containerList = $objectStorage->with()->get();

$containerName = $containerList->getPath();

$shallowContainer = $objectStorage->with('example_container');

$newContainer = $shallowContainer->create();

$updatedContainer = $newContainer->setMeta('Description', 'Adding a meta data')->update();

$reloadedContainer = $newContainer->get();

$result = $newContainer->delete();

// Creating an object is similar to that of container CRUD
// This library will try to guess the content-type for an object if you don't provide it.
// An object without an extension (pseudo sub-directory) will have application/directory content-type.
$newObject = $objectStorage->with('example_container/object.txt')
                            ->setBody('test object')
                            ->setMeta('description', 'first test file')
                            ->create();

// You can copy a local file to Object Storage.
// This will stream local file data to Object Storage. Keep in mind, most PHP configurations will support a file size up to 2 GB.
$newObject = $objectStorage->with('example_container/large_file.zip')
                            ->setLocalFile('/path/to/local/file')
                            ->setMeta('description', 'large local file upload')
                            ->setHeader('Content-type', 'application/zip')
                            ->create();

// You can copy a remote file in Object Storage.
// This will trigger a remote copy on the cluster (which is significantly faster than streaming down and up the file/headers).
$newObject = $objectStorage->with('example_container/large_file_duplicate.zip')
                            ->copyFrom('/example_container/large_file.zip')
                            ->create();

// If you wanted, you can do this all one line.
// Most functions return itself so you can chain method calls except delete method which returns a boolean value.
$result = $objectStorage->with('example_container')
                        ->create()
                        ->setMeta('Description', 'Adding a meta data')
                        ->update()
                        ->get()
                        ->delete();

// When you create a new container or an object, ObjectStorage_Abstract will return itself, not the newly created container or object.
// If you wish to reload the data from ObjectStorage cluster, use ObjectStorage_Abstract::get or ObjectStorage_Abstract::reload methods.
// It will fetch the container info from ObjectStorage and reload $newContainer object with it.
$newContainer = $objectStorage->with('example_container')->create()->reload();

CDN operations

// To create a CDN enabled container
$objectStorage->with('cdn_container')->enableCdn()->create();

// To update an existing container to a CDN enabled container
$objectStorage->with('another_container')->enableCdn()->setTtl(3600)->update();

// You want to see CDN URLs?
$cdnUrls = $container->getCdnUrls();

// CDN purge cache. (In case you modified an object and need to refresh CDN cache.)
$objectStorage05->with('cdn_container/object')->purgeCache();

// CDN load cache
$objectStorage05->with('cdn_container/object')->loadCache();

// If you want to compress *text* files served via CDN.
$results = $objectStorage05->with('')->setContext('cdn')
                    ->setHeader('X-CDN-COMPRESSION', 'true') // Set to "false" to turn off compression
                    ->setHeader('X-CDN-COMPRESSION-MIME', 'text/plain,text/html,text/css,application/x-javascript,text/javascript')
                    ->update();

// If you want to add a custom CDN CNAME. (
// You can add a CNAME to a container level as well. To do so, pass an appropriate container name to with() method
// Keep in mind you can have only one custom CNAME per container
// To find your CNAME endpoint, use "dig" command on your existing CDN host. For example,
// $ dig 1234.http.dal05.cdn.softlayer.net
$results = $objectStorage05->with('')->setContext('cdn')
                    ->setHeader('X-CDN-CNAME-Action', 'add') // Use "delete" if you wish to delete a CNAME
                    ->setHeader('X-Cdn-CNAME', 'cdn.mysite.com')
                    ->update();

Traversing containers or objects

$container = $objectStorage->with('another_container')->get();
if (count($container->objects) > 0) {
    foreach ($container->objects as $shallowObject) {
        $object = $shallowObject->get(); // Defaults to 100 results, pass a parameter to override eg. ->get(500)

        echo $object->getUrl();
        echo $object->getBody();
    }
}

Pseudo-hierarchical directories

/**
 * If you have a container and an object as below and you want to retrieve pseudo sub-directories,
 * use the "prefix" and "delimiter" query parameters.
 *
 * - some_container/sub_dir/2012/object.file
 */

$container = $objectStorage01->with('some_container')
                ->setParam('delimiter', '/')
                ->setParam('prefix', '')
                ->setMime('json')
                ->get();

// Response body (json) will include {"subdir":"sub_dir/"}
// You can traverse to the final object by setting the "subdir" value as the new "prefix" value.
// To retrieve the next level pseudo directory:
...
            ->setParam('prefix', 'sub_dir/');
...

Pagination

/**
 * You can traverse the directories through pages of data using markers.
 *
 */

$container = $objectStorage01->with('some_container')
                ->setParam('marker', '/some_container/last_item_name_on_previous_page.jpg')
                ->get(25);

// You can progress backwards through the directories using "end_marker" too

$container = $objectStorage01->with('some_container')
                ->setParam('end_marker', '/some_container/first_item_name_on_previous_page.jpg')
                ->get(25);

Copy an object to another Object Storage

$objectStorage01 = new ObjectStorage($host01, $username01, $password01);
$objectStorage02 = new ObjectStorage($host02, $username02, $password02);

$object = $objectStorage01->with('container/object')->get();
$objectStorage02->create($object);

Search

$objectOrContainer = $objectStorage05->with('')
                                    ->setContext('search')
                                    ->setFilter('type', 'container')
                                    ->setFilter('q', $searchKeyword)
                                    ->setMime('json')
                                    ->get();

Notes

ObjectStorage_Abstract has many properties but these three are the major componets.

* $objectStorage: holds reference to a ObjectStorage object (optional)
* $request: HTTP request object is consisted of headers and body
* $response: HTTP response object is consisted of headers and body

You can access to HTTP request or response object using ObjectStorage_Abstract::getRequest or ObjectStorage_Abstract::getResponse. You can also use convenience getter and setters. These can help you avoid doing like this:

$container->getResponse()->setMeta('description', 'example meta');
$container->getRequest()->getBody();

But you can do this instead:

$container->setMeta('description', 'example meta');
$container->getBody();

The idea is that you set data to HTTP request and get data from HTTP response.

softlayer / objectstorage

Maintainers

Details