SoftLayer Object Storage PHP Client
PHP
Latest commit 936d763 Aug 12, 2015 @briancline briancline Merge pull request #18 from laiello/master
Update README.markdown
Permalink
Failed to load latest commit information.
docs
lib
tests
.gitignore
COPYING
README.markdown
composer.json

README.markdown

SoftLayer Object Storage PHP Client

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.