Laravel DynamoDB

The Kitar\Dynamodb\Model\Model class extends Eloquent, allowing you to use mutators and serialization. However, unlike standard Eloquent, it forwards calls to the DynamoDB Query Builder instead of a relational query builder, and it cannot handle relations.

Required and Optional Attributes

Implementation Examples

Table with only a Partition Key:

use Kitar\Dynamodb\Model\Model;

class ProductCatalog extends Model
{
    protected $table = 'ProductCatalog';
    protected $primaryKey = 'Id';
    protected $fillable = ['Id', 'Price', 'Title'];
}

Table with a Sort Key:

class Thread extends Model
{
    protected $table = 'Thread';
    protected $primaryKey = 'ForumName';
    protected $sortKey = 'Subject';
    protected $fillable = ['ForumName', 'Subject'];
}

Table with a Sort Key and a Default Sort Key: If sortKeyDefault is set, it will be used when instantiating or calling find() without providing a sort key.

class User extends Model
{
    protected $table = 'User';
    protected $primaryKey = 'email';
    protected $sortKey = 'type';
    protected $sortKeyDefault = 'profile';
    protected $fillable = ['name', 'email', 'password', 'type'];
}

To use DynamoDB for user authentication in Laravel, your model must implement the Illuminate\\\Contracts\\Auth\\Authenticatable contract. You must then register a custom user provider and update your authentication configuration.

1. Register the custom user provider

In your App/Providers/AuthServiceProvider.php, register the dynamodb driver using Kitar\Dynamodb\Model\AuthUserProvider. This provider accepts the hasher, the model class, and optional API token configuration.

2. Update authentication configuration

In config/auth.php, set the driver to dynamodb and specify the model. If you are using API token authentication, you must also provide api_token_name and api_token_index.

3. Handle unique validation for registration

Because DynamoDB does not support the standard Laravel unique validation rule in the same way relational databases do, you should use a closure in your validation logic to manually check for existing records using User::find($value).

// 1. Register provider in App/Providers/AuthServiceProvider.php
use Kitar\Dynamodb\Model\AuthUserProvider;

public function boot()
{
    $this->registerPolicies();

    Auth::provider('dynamodb', function ($app, array $config) {
        return new AuthUserProvider(
            $app['hash'],
            $config['model'],
            $config['api_token_name'] ?? null,
            $config['api_token_index'] ?? null
        );
    });
}

// 2. Configure config/auth.php
'providers' => [
    'users' => [
        'driver' => 'dynamodb',
        'model' => App\User::class,
        'api_token_name' => 'api_token',
        'api_token_index' => 'api_token-index'
    ],
],

// 3. Example validation in a Controller
$request->validate([
    'email' => [
        'required', 'string', 'lowercase', 'email', 'max:255', 
        function ($attribute, $value, $fail) {
            if (User::find($value)) {
                $fail('The '.$attribute.' has already been taken.');
            }
        }
    ],
]);

To use DynamoDB in a Laravel application, follow these two steps:

1. Update config/database.php

Add a dynamodb connection to your connections array:

'connections' => [
    'dynamodb' => [
        'driver' => 'dynamodb',
        'key' => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
        'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
        'token' => env('AWS_SESSION_TOKEN', null),
        'endpoint' => env('DYNAMODB_ENDPOINT', null),
        'prefix' => '', // table prefix
    ],
    ...
],

2. Update .env

Set your default database connection to dynamodb:

DB_CONNECTION=dynamodb

Note for Laravel 11+: Laravel 11 and later versions default to the database driver for session, cache, and queue, which are incompatible with this package. You must switch them to alternative drivers (e.g., file or sync):

SESSION_DRIVER=file
CACHE_STORE=file
QUEUE_CONNECTION=sync

The Kitar\Dynamodb\Model\AuthUserProvider is a custom Laravel user provider designed to work with DynamoDB-backed models. It supports standard identifier-based authentication as well as API token-based authentication using a DynamoDB Global Secondary Index (GSI).

To use it, you must instantiate it with the following parameters:

• hasher: An implementation of Illuminate\Contracts\Hashing\Hasher.
• model: The fully qualified class name of your DynamoDB user model.
• apiTokenName (optional): The name of the attribute in your DynamoDB table that stores the API token.
• apiTokenIndex (optional): The name of the DynamoDB index used to query the API token efficiently.

When apiTokenName and apiTokenIndex are provided, retrieveByCredentials can look up users by their token using a key condition query on the specified index.

// Example of how you might instantiate the provider in a ServiceProvider
$this->app->make('auth')->provider('dynamodb', function ($app, array $config) {
    return new \Kitar\Dynamodb\Model\AuthUserProvider(
        $app->make('hash'),
        $config['model'],
        $config['api_token_name'] ?? null,
        $config['api_token_index'] ?? null
    );
});