README

What is Riverline\DynamoDB

Riverline\DynamoDB is a PHP 5.3 object wrapper for the Amazon PHP DynamoDB SDK. It speed up the manipulation of items and attributes

Requirements

PHP 5.3.5
AWS PHP SDK 2.1.2

Installation

Riverline\DynamoDB is compatible with composer and any prs-0 autoloader

Migration from 1.* to 2.*

Since version 2.0.0, the lib use the new AWS PHP SDK 2.* To migrate to the new version, you need to fix any call to the old AmazonDynamoDB class by using the new Enum classes. For example, \AmazonDynamoDB::TYPE_NUMBER become \Aws\DynamoDb\Enum\Type::NUMBER.

The Connection constructor also change.

Test

Create DynamoDB tables :

Test(id)
TestRange(id, [range])

Define phpunit env vars in ``phpunit.xml.dist`

$ php composer.phar install
$ phpunit

Getting started

Create a new connection

<?php

// Create a DynamoDB connection
$connectionEU = new \Riverline\DynamoDB\Connection('AccessKey', 'SecretKey', \Aws\Common\Enum\Region::EU_WEST_1);

// Attach a simple logger (or write your own logger class)
$connection->setLogger(new \Riverline\DynamoDB\Logger\EchoLogger());
?>

Table operations

<?php

// List Table
$tables = $connection->listTables();

foreach ($tables as $table) {
    echo $table;
}

// Create a new table
$hash                  = new \Riverline\DynamoDB\Table\KeySchemaElement('id', \Aws\DynamoDb\Enum\Type::NUMBER);
$range                 = new \Riverline\DynamoDB\Table\KeySchemaElement('subid', \Aws\DynamoDb\Enum\Type::NUMBER);
$keySchema             = new \Riverline\DynamoDB\Table\KeySchema($hash, $range);
$provisionedThroughput = new \Riverline\DynamoDB\Table\ProvisionedThroughput(3 /* Read */, 5 /* Write */);

$connection->createTable('Product', $keySchema, $provisionedThroughput);

// Wait until active
$connection->waitForTableToBeInState('Product', 'ACTIVE');

// Describe it
$tableDescription = $connection->describeTable('Product');

echo 'Read capacity : '.$tableDescription->getProvisionedThroughput()->getReadCapacity().PHP_EOL;
echo 'Hash key : '.$tableDescription->getKeySchema()->getHash()->getName().PHP_EOL;

// Update it
$provisionedThroughput = new \Riverline\DynamoDB\Table\ProvisionedThroughput(5 /* Read */, 10 /* Write */);
$connection->updateTable('Product', $provisionedThroughput);

// Delete it
$connection->deleteTable('Product');

?>

CRUD

<?php

// Create an item
// Product is a table with hash key 'id' and range key 'subid'
$product = new \Riverline\DynamoDB\Item('Product');
$product['id']    = 102;
$product['subid'] = 202;
$product['title'] = "Product 102-202";
$product['authors'] = array('Author1', 'Author2');

// Save it
$connection->put($product);

// Get it
$product = $connection->get('Product', 102, 202);
echo $product['title'].PHP_EOL;

// Query it on with range condition
$context = new \Riverline\DynamoDB\Context\Query();
$context->setRangeCondition(\Aws\DynamoDb\Enum\ComparisonOperator::BETWEEN, array(200, 205));
$products = $connection->query('Product', 102, $context);

foreach($products as $product) {
    echo $product['title'].PHP_EOL;
}

// Scan it by title and authors fields
$context = new \Riverline\DynamoDB\Context\Scan();
$context->addFilter('title', \Aws\DynamoDb\Enum\ComparisonOperator::CONTAINS, 'Product');
$context->addFilter('authors', \Aws\DynamoDb\Enum\ComparisonOperator::CONTAINS, 'Author1');
$products = $connection->scan('Product', $context);

foreach($products as $product) {
    echo $product['title'].PHP_EOL;
}

// Delete it
$connection->delete('Product', 102, 202);

?>

Complex Query

<?php

// Query with range condition, limit and consistent read
$context = new \Riverline\DynamoDB\Context\Query();
$context->setRangeCondition(\Aws\DynamoDb\Enum\ComparisonOperator::BETWEEN, array(200, 205));
$context->setLimit(2);
$context->setConsistentRead(true);
$products = $connection->query('Product', 102, $context);

// Return only some attributes with backward index
$context = new \Riverline\DynamoDB\Context\Query();
$context->setRangeCondition(\Aws\DynamoDb\Enum\ComparisonOperator::BETWEEN, array(200, 205));
$context->setAttributesToGet(array('id', 'title'));
$context->ScanIndexForward(false);
$products = $connection->query('Product', 102, $context);

?>

Complex Scan

<?php

// Scan with limit
$context = new \Riverline\DynamoDB\Context\Scan();
$context->addFilter('title', \Aws\DynamoDb\Enum\ComparisonOperator::CONTAINS, 'Product');

do {
    $products = $connection->scan('Product', $context);

    foreach($products as $product) {
        echo $product['title'].PHP_EOL;
    }

    // Get the next context to continue
    $context = $products->getNextContext();
} while ($products->more() /* more products to retrieve */);

?>

Batch operations

<?php

// Batch Write
$batchWrite = new \Riverline\DynamoDB\Context\BatchWrite();

// Add some products
for($i=1; $i < 20; $i++) {
    $product = new \Riverline\DynamoDB\Item('Product');
    $product['id']    = 102;
    $product['subid'] = $i;
    $product['title'] = "Product 102-".$i;
    $product['authors'] = array('Author1', 'Author2');

    $batchWrite->addItemToPut($product);
}

// Delete one product
$batchWrite->addKeyToDelete('Product', 102, 202);

$connection->batchWrite($batchWrite);

// Batch Get
$batchGet = new \Riverline\DynamoDB\Context\BatchGet();
$batchGet->addKey('Product', 102, 1);
$batchGet->addKey('Product', 102, 3);
$batchGet->addKey('Product', 102, 5);
$batchGet->addKey('Product', 102, 15);

do {
    $result = $connection->batchGet($batchGet);

    foreach ($result['Product'] as $product) {
        echo $product['title'].PHP_EOL;
    }

    // Get the new batchGet context with the unprocessed keys
    $batchGet = $result->getUnprocessedKeysContext();
} while($batchGet /* $batch is null if there are not unprocessed keys */);

// Repeater helper class

$repeater = new \Riverline\DynamoDB\Repeater($connection);
// Repeat batchWrite request until everything is processed
// Manage "provisioned throughput exceeded" server errors
$repeater->batchWrite($batchWrite);

?>

Get statistics

<?php

// Get consumed write units
echo $connection->getConsumedWriteUnits('Product').PHP_EOL;

// Get consumed read units for all tables
echo $connection->getConsumedReadUnits().PHP_EOL;

?>

riverline / dynamodb

Maintainers

Details