-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
0 parents
commit 39363b6
Showing
26 changed files
with
1,704 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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" | ||
} | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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'), | ||
], | ||
], | ||
]; |
Oops, something went wrong.