Dynamo Db Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require async-aws/dynamo-db
   

   Ensure aws/aws-sdk-php is also installed (dependency).

2. Basic Client Initialization

   use AsyncAws\DynamoDb\DynamoDbClient;
   
   $client = new DynamoDbClient([
       'region' => 'us-east-1',
       'version' => 'latest',
       'credentials' => [
           'key'    => env('AWS_ACCESS_KEY_ID'),
           'secret' => env('AWS_SECRET_ACCESS_KEY'),
       ],
   ]);
   

3. First Use Case: Query a Table

   $result = $client->query([
       'TableName' => 'Users',
       'KeyConditionExpression' => 'id = :id',
       'ExpressionAttributeValues' => [':id' => ['S' => '123']],
   ]);
   

Where to Look First

• Documentation (if available) for API reference.
• src/ for core classes (DynamoDbClient, Command, Model).
• Tests (tests/ directory) for usage examples and edge cases.

Implementation Patterns

1. Command-Based Workflows

Leverage the Command facade for fluent, chainable operations:

use AsyncAws\DynamoDb\Command\GetItem;
use AsyncAws\DynamoDb\Command\PutItem;

$getItem = new GetItem('Users', ['id' => ['S' => '123']]);
$item = $client->getItem($getItem);

$putItem = new PutItem('Users', [
    'id' => ['S' => '123'],
    'name' => ['S' => 'John Doe'],
]);
$client->putItem($putItem);

2. Batch Operations

Use BatchWriteItem for bulk inserts/updates/deletes:

$batchWrite = new BatchWriteItem([
    'RequestItems' => [
        'Users' => [
            new PutRequest(['id' => ['S' => '456'], 'name' => ['S' => 'Jane Smith']]),
            new DeleteRequest(['id' => ['S' => '789']]),
        ],
    ],
]);
$client->batchWriteItem($batchWrite);

3. Transactions

For multi-table atomic operations:

$transactWrite = new TransactWrite([
    'TransactItems' => [
        new TransactPut(['TableName' => 'Users', 'Item' => [...]]),
        new TransactUpdate(['TableName' => 'Orders', 'Update' => [...]]),
    ],
]);
$client->transactWriteItems($transactWrite);

4. Pagination

Handle large result sets with LastEvaluatedKey:

$lastKey = null;
do {
    $query = new Query('Users', 'id', ['S' => '123'], $lastKey);
    $result = $client->query($query);
    $lastKey = $result->getLastEvaluatedKey();
} while ($lastKey);

5. Integration with Laravel

• Service Provider Binding:

  $this->app->singleton(DynamoDbClient::class, function ($app) {
      return new DynamoDbClient($app['config']['aws']);
  });
  

• Eloquent-like Models (if extending):

  class UserModel extends \AsyncAws\DynamoDb\Model {
      protected $table = 'Users';
      protected $primaryKey = 'id';
  }
  

Gotchas and Tips

Pitfalls

1. Attribute Value Formatting DynamoDB requires strict typing (e.g., ['S' => 'string'] for strings). Fix: Use AttributeValue helper or validate inputs:

   $client->putItem(new PutItem('Users', [
       'id' => AttributeValue::fromString('123'),
       'metadata' => AttributeValue::fromMap(['key' => 'value']),
   ]));
   

2. Throttling DynamoDB enforces provisioned throughput. Fix: Implement exponential backoff or use ProvisionedThroughputExceededException handling:

   try {
       $client->query($query);
   } catch (ProvisionedThroughputExceededException $e) {
       sleep(1); // Retry after delay
   }
   

3. Case Sensitivity Table/attribute names are case-sensitive in DynamoDB. Tip: Use constants or config for names:

   class DynamoDbTables {
       public const USERS = 'Users';
   }
   

4. Async vs. Sync The package supports async operations (e.g., Promise integration). Tip: Use await for async calls:

   $result = await($client->query($query));
   

Debugging Tips

• Enable AWS SDK Debugging:

  putenv('AWS_DEBUG=1');
  

• Log Raw Requests/Responses:

  $client->setHandlerStack(new HandlerStack([
      new \Aws\Common\Credential\CredentialProviderChain(),
      new \Aws\Common\Middleware\LoggerMiddleware(
          new \Monolog\Logger('DynamoDb')
      )
  ]));
  

Extension Points

1. Custom Middleware Add middleware to the handler stack for logging/auditing:

   $client->getHandlerStack()->push(new class implements Middleware {
       public function __invoke($request, $handler) {
           // Pre-process request
           $response = $handler->handle($request);
           // Post-process response
           return $response;
       }
   });
   

2. Event Dispatching Trigger events on CRUD operations (e.g., via Laravel Events):

   event(new UserCreated($item));
   

3. Repository Pattern Abstract DynamoDB operations into repositories:

   class UserRepository {
       public function __construct(private DynamoDbClient $client) {}
   
       public function findById(string $id): array {
           return $this->client->getItem(new GetItem('Users', ['id' => ['S' => $id]]));
       }
   }
   

Config Quirks

• Region Overrides: Set region per-command:

  $client->query($query, ['region' => 'eu-west-1']);
  

• Endpoint URL: Use for local DynamoDB (e.g., Docker):

  $client = new DynamoDbClient(['endpoint' => 'http://localhost:8000']);