vvvlad/abstractds

This library is intended to implement an abstract data store layer against AWS services such as SimpleDB, DynamoDB and S3. The library will expose a Service Provider for Laravel 4.

0.1.1 2014-06-03 22:21 UTC

README

Total Downloads Latest Stable Version Build Status

These libraries are intended as a simple set of wrappers to abstract away basic functionality of several data stores using a consistent find/get/set/delete set of calls.

Currently, they implement abstraction for AWS SimpleDB and S3. More will be made available as time allows. The idea is to provide a simple and relatively easy way to store schema-less structured data. I realize that different data stores have different characteristics and the provided methods will reflect that. The intent is not to bring all to a common denominator, but to provide a simple to use interface for basic use cases and proof of concept functionality.

A provider for Laravel 4 is also included.

Installation

Install AbstractDS via composer, edit the composer.json and add:

"require": {
    "php": ">=5.3.0",
    "vvvlad/abstractds": "dev-master"
}

Then update the project dependencies via:

terminal$ composer update

Usage

Autoload the composer dependencies:

require('../vendor/autoload.php');

If not used in conjunction with Laravel 4, also load the AWS client:

// Create a service locator using a configuration file, see link below for format
// http://docs.aws.amazon.com/aws-sdk-php/guide/latest/quick-start.html
$aws = Aws::factory('../.aws/config.php');

... and initialize the desired class:

$sdb = new \UAService\SDb($aws); // SimpleDB
$s3ds = new \UAService\S3ds($aws); // S3

In Laravel 4, declare the service provider by editing the app/config/app.php file, look for:

'providers' => array(
    'Illuminate\Foundation\Providers\ArtisanServiceProvider',
    [...]
    'AbstractDS\AbstractDSServiceProvider',
),

...then call the service provider as needed:

$sdb = App::make('abstractds.sdb'); // SimpleDB
$s3ds = App::make('abstractds.s3ds'); // S3

Initialize the table/bucket/domain, method issues an Exception on failure:

$sdb->init('my-domain'); // If the domain doesn't exist and the AWS user has permissions, the domain will be created
$s3ds->init('my-bucket'); // If the bucket doesn't exist, it will NOT be created, instead an exception is issued

Find objects in the table/bucket/domain, method issues an Exception on failure, but not if no objects were found:

$array = $sdb->find('my-domain'); // the array key is the object ID, each record is a set of key = value pairs
$array = $s3ds->find('my-bucket'); // the array key is the object ID, the record is a set of key = value metadata pairs

Get an object, method issues an Exception on failure:

$array = $sdb->get('my-domain', 'key1'); // set of key = value pairs
$blob = $s3ds->get('my-bucket', 'some/file'); // returns the content of the object (unstructured)

Set/Replace an object, method issues an Exception on failure:

$sdb->set('my-domain', 'key1', array('key' => 'value'));
$s3ds->set('my-bucket', 'some/file', 'File body');

Delete an object, method issues an Exception on failure:

$sdb->delete('my-domain', 'key1');
$s3ds->delete('my-bucket', 'some/file');

Advanced Options

SimpleDB is a string oriented data store, all keys and all values are strings. This means any type of sorting or query matching is made lexigraphically. AbstractDS contains a mechanism to normalize/de-normalize record attributes to mask this limitation.

  • any object or array provided as an attribute value, will be JSON encoded. On retrieval, Sdb attempts to JSON decode the string, to see if it can restore an array
  • any date/time provided as an attribute value will be normalized to ISO 8601 format (assuming it can be interpreted as a date and/or time by strtotime())
  • booleans are represented as the string '1' or '0', they are converted back on retrieval
  • numbers are zero padded to 12 decimals (before the decimal point), the padding is removed on retrieval

If planning to access this data using a 3rd party system, please take these considerations into account.

Because AWS SimpleDB has a consistent read option, this option is exposed to the Sdb::get() method, but off by default. But if a consistent read is necessary, set the 3rd parameter for the get method to TRUE, at the cost of performance.

The Sdb::find() method accepts an optional list of search criteria. They are provided as key = value pairs, and are aggregated in a logic AND operation. The criteria are accepted in the following format:

$criteria = array(
    'attribute1' = 'Value1',
    'attribute2 [operator]' = 'Value2'
);

... where [operator] can be:

!=, <, >, <=, >=, like, not like, is null, is not null, between, in

Please note that for the last 2 (between, in) the system will not normalize the value.