AWS DynamoDB

AWS DynamoDB is a managed NoSQL database service that provides fast and predictable performance with seamless scalability. This driver provides a Key/Value interface for DynamoDB.

<?php
$dynamodb = \ByJG\AnyDataset\NoSql\Factory::getInstance('dynamodb://access_key:secret_key@region/tablename');

The full connection string format:

dynamodb://access_key:secret_key@region/tablename?option1=value1&option2=value2

Example:

dynamodb://AKA12345678899:aaaaaaaaaaaaaaaaaaaaaaaaa@us-east-1/mytable

Connection Options

You can add any extra arguments supported by the DynamoDB API to the query string. For a comprehensive list, refer to the AWS SDK for PHP Client Configuration.

Custom Endpoint

One of the most common parameters is endpoint, which allows you to set a custom endpoint for DynamoDB Local (for development/testing):

dynamodb://access_key:secret_key@us-east-1/tablename?endpoint=http://localhost:8000

DynamoDB Data Structure

DynamoDB stores information using a specific attribute format that differs from typical object structures.

For example, a DynamoDB native representation looks like this:

[
    'id'      => ['N' => '1201'],
    'time'    => ['N' => $time],
    'error'   => ['S' => 'Executive overflow'],
    'message' => ['S' => 'no vacant areas']
]

Simplified Format

This library abstracts the DynamoDB format to let you use a more familiar representation:

[
    'id'      => 1201,
    'time'    => $time,
    'error'   => 'Executive overflow',
    'message' => 'no vacant areas'
]

Type Definitions

When using the put/get/remove methods, you need to provide type information through the options parameter to define the data model.

This library provides a DynamoDbAttributeType enum for defining attribute types, making your code more maintainable and less error-prone:

<?php
use ByJG\AnyDataset\NoSql\Enum\DynamoDbAttributeType;

// Example of options using the enum
$options = [
    "KeyName" => "id",
    "Types" => [
        "id" => DynamoDbAttributeType::NUMBER,
        "time" => DynamoDbAttributeType::NUMBER,
        "error" => DynamoDbAttributeType::STRING,
        "message" => DynamoDbAttributeType::STRING
    ]
];

Key Attribute Type Matching

Important

The attribute type you define for your primary key in the options array MUST match the attribute type defined in your DynamoDB table schema. Mismatching these types will result in a ValidationException: Type mismatch for key error.

For example, if your DynamoDB table defines the id attribute as type NUMBER (N), you must use:

$options = [
    "KeyName" => "id",
    "Types" => [
        "id" => DynamoDbAttributeType::NUMBER, // This must match the table schema
        // other attributes...
    ]
];

Similarly, if your table defines the key as STRING (S), you must use DynamoDbAttributeType::STRING.

Available Attribute Types

The DynamoDbAttributeType enum provides the following types:

Enum Case	Value	Description
NUMBER	'N'	Represents a number
STRING	'S'	Represents a string
BINARY	'B'	Represents binary data
BOOLEAN	'BOOL'	Represents a boolean value
NULL	'NULL'	Represents a null value
MAP	'M'	Represents a map (nested attributes)
LIST	'L'	Represents a list (ordered collection)
STRING_SET	'SS'	Represents a set of strings
NUMBER_SET	'NS'	Represents a set of numbers
BINARY_SET	'BS'	Represents a set of binary values

Basic Operations

Inserting/Updating data

<?php
use ByJG\AnyDataset\NoSql\Enum\DynamoDbAttributeType;
use ByJG\AnyDataset\NoSql\Factory;

$dynamodb = Factory::getInstance('dynamodb://....');

// Define types using the enum
$options = [
    "KeyName" => "id",
    "Types" => [
        "id" => DynamoDbAttributeType::NUMBER,
        "time" => DynamoDbAttributeType::NUMBER,
        "error" => DynamoDbAttributeType::STRING,
        "message" => DynamoDbAttributeType::STRING
    ]
];

$dynamodb->put(
    1201,  // Primary key value
    [
        "time" => 1234567899,
        "error" => 'Executive overflow',
        "message" => "No Vacant Areas"
    ],
    $options  // Type definitions
);

observação

The key value (1201) is passed as the first parameter to the put method. You don't need to include this value in the data array as the library will automatically add it for you.

Retrieving a value

<?php
use ByJG\AnyDataset\NoSql\Enum\DynamoDbAttributeType;
use ByJG\AnyDataset\NoSql\Factory;

$dynamodb = Factory::getInstance('dynamodb://....');

$options = [
    "KeyName" => "id",
    "Types" => [
        "id" => DynamoDbAttributeType::NUMBER,
    ]
];

$value = $dynamodb->get(1201, $options);

/* Returns:
[
    'id'      => 1201,
    'time'    => 1234567899,
    'error'   => 'Executive overflow',
    'message' => 'No Vacant Areas'
]
*/

Checking if a key exists

<?php
use ByJG\AnyDataset\NoSql\Enum\DynamoDbAttributeType;
use ByJG\AnyDataset\NoSql\Factory;

$dynamodb = Factory::getInstance('dynamodb://....');

$options = [
    "KeyName" => "id",
    "Types" => [
        "id" => DynamoDbAttributeType::NUMBER,
    ]
];

if ($dynamodb->has(1201, $options)) {
    echo "Key exists!";
}

Removing a value

<?php
use ByJG\AnyDataset\NoSql\Enum\DynamoDbAttributeType;
use ByJG\AnyDataset\NoSql\Factory;

$dynamodb = Factory::getInstance('dynamodb://....');

$options = [
    "KeyName" => "id",
    "Types" => [
        "id" => DynamoDbAttributeType::NUMBER,
    ]
];

$dynamodb->remove(1201, $options);

Querying Data

To get a list of objects, you need to use either KeyConditions (for queries on the primary key) or ScanFilter (for scanning the entire table) in the options array.

Query using KeyConditions

<?php
use ByJG\AnyDataset\NoSql\Enum\DynamoDbAttributeType;
use ByJG\AnyDataset\NoSql\Factory;

$dynamodb = Factory::getInstance('dynamodb://....');

$options = [
   "TableName" => "mytable", // Table name is required
   "KeyConditions" => [
       "id" => [
           "AttributeValueList" => [
               [DynamoDbAttributeType::NUMBER->value => "1201"]
           ],
           "ComparisonOperator" => "EQ"
       ]
   ],
   "Types" => [
       "id" => DynamoDbAttributeType::NUMBER,
       "time" => DynamoDbAttributeType::NUMBER,
       "error" => DynamoDbAttributeType::STRING,
       "message" => DynamoDbAttributeType::STRING
   ]
];

$iterator = $dynamodb->getIterator($options);
print_r($iterator->toArray());

informação

When using the query operation, the key must match the key used in the table schema, and the type must also match.

Scan using ScanFilter

<?php
use ByJG\AnyDataset\NoSql\Enum\DynamoDbAttributeType;
use ByJG\AnyDataset\NoSql\Factory;

$dynamodb = Factory::getInstance('dynamodb://....');

$options = [
   "TableName" => "mytable", // Table name is required 
   "ScanFilter" => [
       "error" => [
           "AttributeValueList" => [
               [DynamoDbAttributeType::STRING->value => "Executive overflow"]
           ],
           "ComparisonOperator" => "EQ"
       ]
   ],
   "Types" => [
       "id" => DynamoDbAttributeType::NUMBER,
       "time" => DynamoDbAttributeType::NUMBER,
       "error" => DynamoDbAttributeType::STRING,
       "message" => DynamoDbAttributeType::STRING
   ]
];

$iterator = $dynamodb->getIterator($options);
print_r($iterator->toArray());

Performance

The Scan operation searches through the entire table, which can be slower but allows you to filter on non-key attributes. For production use with large tables, prefer Query operations when possible.

Working with Complex Data Types

Automatic Type Conversion

The AWS DynamoDB driver handles complex data types automatically. You just need to specify the correct type in the options and pass the data in normal PHP format.

Boolean Values

Boolean values should be actual PHP booleans:

<?php
use ByJG\AnyDataset\NoSql\Enum\DynamoDbAttributeType;
use ByJG\AnyDataset\NoSql\Factory;

$options = [
    "KeyName" => "id",
    "Types" => [
        "id" => DynamoDbAttributeType::STRING,
        "isActive" => DynamoDbAttributeType::BOOLEAN
    ]
];

$dynamodb = Factory::getInstance('dynamodb://....');
$dynamodb->put(
    'user123',
    [
        "isActive" => true  // Use actual boolean, not string
    ],
    $options
);

Lists

For LIST types, you can use a regular PHP array:

<?php
use ByJG\AnyDataset\NoSql\Enum\DynamoDbAttributeType;
use ByJG\AnyDataset\NoSql\Factory;

$options = [
    "KeyName" => "id",
    "Types" => [
        "id" => DynamoDbAttributeType::STRING,
        "items" => DynamoDbAttributeType::LIST
    ]
];

$dynamodb = Factory::getInstance('dynamodb://....');
$dynamodb->put(
    'order123',
    [
        "items" => ["item1", "item2", "item3"]  // Regular PHP array
    ],
    $options
);

Maps

MAP types can also use a regular PHP associative array:

<?php
use ByJG\AnyDataset\NoSql\Enum\DynamoDbAttributeType;
use ByJG\AnyDataset\NoSql\Factory;

$options = [
    "KeyName" => "id",
    "Types" => [
        "id" => DynamoDbAttributeType::STRING,
        "details" => DynamoDbAttributeType::MAP
    ]
];

$dynamodb = Factory::getInstance('dynamodb://....');
$dynamodb->put(
    'product123',
    [
        "details" => [
            "name" => "Product Name",
            "price" => 99.99,
            "inStock" => true
        ]
    ],
    $options
);

NULL Values

NULL types in DynamoDB can be represented by PHP null:

<?php
use ByJG\AnyDataset\NoSql\Enum\DynamoDbAttributeType;
use ByJG\AnyDataset\NoSql\Factory;

$options = [
    "KeyName" => "id",
    "Types" => [
        "id" => DynamoDbAttributeType::STRING,
        "optional" => DynamoDbAttributeType::NULL
    ]
];

$dynamodb = Factory::getInstance('dynamodb://....');
$dynamodb->put(
    'record123',
    [
        "optional" => null  // Use PHP null
    ],
    $options
);

Set Types

For SET types (STRING_SET, NUMBER_SET, BINARY_SET), use regular PHP arrays:

<?php
use ByJG\AnyDataset\NoSql\Enum\DynamoDbAttributeType;
use ByJG\AnyDataset\NoSql\Factory;

$options = [
    "KeyName" => "id",
    "Types" => [
        "id" => DynamoDbAttributeType::STRING,
        "tags" => DynamoDbAttributeType::STRING_SET,
        "ratings" => DynamoDbAttributeType::NUMBER_SET
    ]
];

$dynamodb = Factory::getInstance('dynamodb://....');
$dynamodb->put(
    'post123',
    [
        "tags" => ["php", "aws", "dynamodb"],  // String set
        "ratings" => [4, 5, 3, 5]              // Number set
    ],
    $options
);

informação

The DynamoDB driver handles the conversion to and from DynamoDB attribute format automatically, making it easier to work with complex types.

Connection Options​

Custom Endpoint​

DynamoDB Data Structure​

Type Definitions​

Key Attribute Type Matching​

Available Attribute Types​

Basic Operations​

Inserting/Updating data​

Retrieving a value​

Checking if a key exists​

Removing a value​

Querying Data​

Query using KeyConditions​

Scan using ScanFilter​

Working with Complex Data Types​

Boolean Values​

Lists​

Maps​

NULL Values​

Set Types​

Further Reading​