First

.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: PHP Composer
+
+on:
+  push:
+    branches: [ "master", "develop"]
+  pull_request:
+    branches: [ "master" ]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Validate composer.json and composer.lock
+      run: composer validate --strict
+
+    - name: Cache Composer packages
+      id: composer-cache
+      uses: actions/cache@v3
+      with:
+        path: vendor
+        key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-php-
+
+    - name: Install dependencies
+      run: composer install --prefer-dist --no-progress
+
+    - name: Setup DynamoDB Local
+      uses: rrainn/dynamodb-action@v2.0.1
+      with:
+        sharedDb: true
+        port: 8000
+        cors: '*'
+    - name: Run tests
+      run: vendor/bin/phpunit --testdox
+

.gitignore

@@ -0,0 +1,25 @@
+/vendor/
+node_modules/
+npm-debug.log
+yarn-error.log
+.idea
+composer.lock
+
+# Laravel 4 specific
+bootstrap/compiled.php
+app/storage/
+
+# Laravel 5 & Lumen specific
+public/storage
+public/hot
+
+# Laravel 5 & Lumen specific with changed public path
+public_html/storage
+public_html/hot
+
+storage/*.key
+.env
+Homestead.yaml
+Homestead.json
+/.vagrant
+.phpunit.result.cache

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Tinashe Musonza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,180 @@
+# DynamoBreeze
+
+A Laravel package for easily interacting with Amazon DynamoDB using a single-table approach and a facade for streamlined developer experience.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Example Usage](#example-usage)
+- [Testing](#testing)
+- [Contribution](#contribution)
+- [License](#license)
+- [Contact](#contact)
+
+## Installation
+
+### Via Composer
+
+```bash
+composer require musonza/dynamo-breeze
+```
+
+### Configuration
+
+After installing the package, publish the configuration file by running:
+
+```bash
+php artisan vendor:publish --provider="Musonza\DynamoBreeze\DynamoBreezeServiceProvider" --tag="config"
+```
+
+## Example Usage
+
+With the DynamoBreeze facade, you can interact with DynamoDB in a more expressive and straightforward manner. Here are examples demonstrating its usage:
+
+Below is a fundamental example of how to interact with DynamoDB using the DynamoBreeze package. DynamoBreeze is designed to accommodate a single-table design principle, which means you can create a generic table that can host multiple entities and utilize various access patterns efficiently.
+
+In your `dynamo-breeze.php` config file:
+
+```php
+return [
+    // 'tables' holds the configuration for all the DynamoDB tables that this package will interact with.
+    'tables' => [
+        // Each table has its own configuration nested under a unique logical identifier used in your application code to reference the table configuration.
+        'social_media' => [
+            /*
+            * 'table_name' is the name of the DynamoDB table as defined in AWS.
+            */
+            'table_name' => 'SocialMediaTable',
+
+            /*
+            * 'partition_key' specifies the primary key attribute name of the table.
+            */
+            'partition_key' => 'PK',
+
+            /*
+            * 'sort_key' specifies the sort key attribute name of the table.
+            * If a table doesn't have a sort key, you can omit this field.
+            */
+            'sort_key' => 'SK',
+
+            /*
+            * 'attributes' define the attributes and their types that the model will interact with.
+            * It's used for actions like creating tables or validating input.
+            * Common types: 'S' => String, 'N' => Number, 'B' => Binary.
+            */
+            'attributes' => [
+                'PK' => 'S',
+                'SK' => 'S',
+                // ...
+            ],
+
+            /*
+            * 'access_patterns' define various access patterns to use with the table.
+            * Each access pattern has a unique name and associated settings.
+            */
+            'access_patterns' => [
+                'FetchUserPosts' => [
+                    'gsi_name' => null,
+                    'key_condition_expression' => 'PK = :pk_val AND begins_with(SK, :sk_prefix_val)',
+                    'expression_attribute_values' => [
+                        ':pk_val' => ['S' => 'USER#<user_id>'],
+                        ':sk_prefix_val' => ['S' => 'POST#'],
+                    ],
+                ],
+                'FetchPostComments' => [
+                    'gsi_name' => null,
+                    'key_condition_expression' => 'PK = :pk_val AND begins_with(SK, :sk_prefix_val)',
+                    'expression_attribute_values' => [
+                        ':pk_val' => ['S' => 'POST#<post_id>'],
+                        ':sk_prefix_val' => ['S' => 'COMMENT#'],
+                    ],
+                ],
+                // ...
+            ],
+            // ... additional settings for the table
+        ],
+
+        /*
+        * Additional tables, such as 'products', can have similar configurations.
+        * Adapt each table configuration to match its structure and access patterns in DynamoDB.
+        */
+        'products' => [
+            // ... configuration for the 'products' table
+        ],
+        // ... configurations for other tables
+    ],
+
+    /*
+    * 'sdk' holds the configuration for the AWS SDK.
+    */
+    'sdk' => [
+        'region'   => env('DYNAMODB_REGION', 'us-west-2'),
+        'version'  => env('DYNAMODB_VERSION', 'latest'),
+        'credentials' => [
+            'key'    => env('AWS_ACCESS_KEY_ID'),
+            'secret' => env('AWS_SECRET_ACCESS_KEY'),
+        ],
+    ],
+];
+```
+
+#### Fetch User Posts
+
+```php
+use Musonza\DynamoBreeze\Facades\DynamoBreeze;
+
+$result = DynamoBreeze::table('social_media')
+    ->accessPattern('FetchUserPosts', [
+        ':pk_val' => 'USER#' . $userId,
+        ':sk_val' => 'POST#',
+    ])
+    ->get();
+```
+
+#### Fetch Post Comments
+
+```php
+$comments = DynamoBreeze::table('social_media')
+    ->accessPattern('FetchPostComments', [
+        ':pk_val' => 'POST#' . $postId,
+        ':sk_val' => 'COMMENT#',
+    ])
+    ->get();
+```
+
+#### Fetch Post Likes
+
+```php
+$likes = DynamoBreeze::table('social_media')
+    ->accessPattern('FetchPostLikes', [
+        ':pk_val' => 'POST#' . $postId,
+        ':sk_val' => 'LIKE#',
+    ])
+    ->get();
+```
+
+#### Fetch Conversation Messages
+
+```php
+$messages = DynamoBreeze::table('social_media')
+    ->accessPattern('FetchConversationMessages', [
+        ':pk_val' => 'CONVERSATION#' . $conversationId,
+        ':sk_val' => 'MESSAGE#',
+    ])
+    ->get();
+```
+
+Ensure that keys, table names, and access patterns align with your actual DynamoDB setup to avoid discrepancies or errors.
+
+## Testing
+
+`composer test`
+
+## Contribution
+
+Contributions are welcome and will be fully credited. Please see [CONTRIBUTING](.github/CONTRIBUTING.md) and [CODE_OF_CONDUCT](.github/CODE_OF_CONDUCT.md) for details.
+
+## License
+
+DynamoBreeze is open-sourced software licensed under the [MIT license](LICENSE.md).

composer.json

@@ -0,0 +1,69 @@
+{
+    "name": "musonza/dynamo-breeze",
+    "description": "A Laravel package for easy interaction with DynamoDB using a single-table approach.",
+    "type": "library",
+    "license": "MIT",
+    "require": {
+        "php": "^7.4 || ^8.0",
+        "illuminate/support": "^9.47.0 || ^10.0.0 || ^11.0.0",
+        "aws/aws-sdk-php": "^3.0"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^9.4",
+        "orchestra/testbench": "^8.0",
+        "phpstan/phpstan": "^1.9",
+        "nunomaduro/larastan": "^2.6",
+        "vimeo/psalm": "^5.4",
+        "rector/rector": "^0.15.2",
+        "laravel/pint": "^1.3",
+        "tuupola/ksuid": "^2.1"
+    },
+    "autoload": {
+        "psr-4": {
+            "Musonza\\DynamoBreeze\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Musonza\\DynamoBreeze\\Tests\\": "tests/"
+        }
+    },
+    "extra": {
+        "laravel": {
+            "providers": [
+                "Musonza\\DynamoBreeze\\DynamoBreezeServiceProvider"
+            ]
+        }
+    },
+    "minimum-stability": "dev",
+    "prefer-stable": true,
+    "scripts": {
+        "test:lint-fix": "./vendor/bin/pint",
+        "test:psalm": "vendor/bin/psalm",
+        "test:unit": "vendor/bin/phpunit --filter=unit",
+        "test:feature": "vendor/bin/phpunit --filter=feature",
+        "test:analyse": "vendor/bin/phpstan analyse --memory-limit=2G --ansi",
+        "test:lint": "./vendor/bin/pint --test",
+        "test:refactor": "rector --dry-run",
+        "test": [
+            "@test:lint-fix",
+            "@test:refactor",
+            "@test:analyse",
+            "@test:psalm",
+            "@test:unit",
+            "@test:feature"
+        ]
+    },
+    "config": {
+        "sort-packages": true
+    },
+    "authors": [
+        {
+            "name": "Tinashe Musonza"
+        }
+    ],
+    "support": {
+        "issues": "https://github.com/musonza/dynamo-breeze/issues",
+        "source": "https://github.com/musonza/dynamo-breeze"
+    }
+}

config/dynamo-breeze.php

@@ -0,0 +1,49 @@
+<?php
+
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | DynamoDB Tables Configuration
+    |--------------------------------------------------------------------------
+    |
+    | Here you may define all of the table configurations for the application
+    | including their access patterns, primary keys, and indexes.
+    |
+    */
+
+    'tables' => [
+        'example_table' => [
+            'table_name' => env('DYNAMODB_TABLE', 'ExampleTable'),
+            'partition_key' => 'exampleId',
+            'sort_key' => null,
+            'attributes' => [
+                'exampleId' => 'S',
+            ],
+            'access_patterns' => [
+                'ExampleAccessPattern' => [
+                    'gsi_name' => 'GSI_Example',
+                    'key_condition_expression' => 'exampleId = :exampleId_val',
+                ],
+            ],
+        ],
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | AWS SDK Configuration
+    |--------------------------------------------------------------------------
+    |
+    | Here you may configure AWS SDK settings, which will be used when
+    | interacting with AWS services like DynamoDB.
+    |
+    */
+
+    'sdk' => [
+        'region' => env('DYNAMODB_REGION', 'us-west-2'),
+        'version' => env('DYNAMODB_VERSION', 'latest'),
+        'credentials' => [
+            'key' => env('AWS_ACCESS_KEY_ID'),
+            'secret' => env('AWS_SECRET_ACCESS_KEY'),
+        ],
+    ],
+];