Download the PHP package musonza/dynamo-breeze without Composer

DynamoBreeze

DynamoBreeze is a Laravel package designed to simplify interactions with Amazon DynamoDB. While it accommodates the single-table design principle, it's versatile enough to support multiple-table usage, providing a seamless experience regardless of your database's architecture. Importantly, it enables the use of multiple AWS credentials, a key feature for applications requiring access to tables across different AWS accounts or those utilizing specific IAM keys for certain tables. Through a fluent, expressive facade, DynamoBreeze makes it easier than ever to work with DynamoDB.

Key Features

• Single or Multiple Table Support: Whether you're adhering to a single-table design or using multiple tables, DynamoBreeze adapts to your needs, allowing for efficient interactions with your data without the complexity.
• Multiple AWS Credentials: DynamoBreeze's architecture facilitates the use of different AWS credentials for various tables, perfect for interacting with multiple AWS accounts or applying specific keys and secrets to individual tables. This capability ensures a flexible and secure approach to managing your data across diverse environments.
• Expressive Syntax: Leverage the power of fluent syntax to build your DynamoDB queries, making them more readable and maintainable.

• Streamlined Configuration: Define your table structures and access patterns in a central configuration, making it easy to manage and query your data.

• Customizable: Ready to be used out of the box, but built with customization in mind, so you can adjust it according to your application's requirements.

Table of Contents

• Installation
• Configuration
• Example Usage
• Handling Responses with DynamoBreezeResult
• Extending Query Parameter Mappings
• Pagination
• Batch Retrieval with batchGet
• Projection Expressions
• ReturnConsumedCapacity
• Dynamo Breeze Pattern Details
• Testing
• Contribution
• License
• Contact

Installation

Via Composer

Configuration

After installing the package, publish the configuration file by running:

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:

Fetch User Posts

Fetch Post Comments

Handling Responses with DynamoBreezeResult

All operations performed through the DynamoBreeze facade will return an instance of DynamoBreezeResult. This object provides a convenient way to interact with the data returned from DynamoDB, offering several methods to retrieve specific portions of the AWS result or the entire raw result.

Methods Available

• getItems(): Returns an array of items from the result. If no items are found, it returns null.

• getCount(): Retrieves the count of returned items. If no count is provided in the result, it returns null.

• getRawResult(): Provides access to the original Aws\Result object, allowing you to retrieve any data or metadata returned from the AWS SDK's DynamoDB client.

Example

Extending Query Parameter Mappings

DynamoBreeze provides a core set of mappings that translate specific configuration keys to the corresponding DynamoDB query parameters. These mappings are used internally to build queries from your application's configurations.

While the default mappings cover a wide range of common use cases, there might be scenarios where you need to extend or override these mappings. For such cases, DynamoBreeze offers a flexible solution through the additional_query_mappings configuration.

Adding Custom Mappings

If you need to add new mappings that aren't included in the default set, you can define them in your application's dynamo-breeze configuration file under the additional_query_mappings key.

Here's an example of how to set up additional_query_mappings:

In this example, your_config_key is the key you use in your application's configuration, and DynamoQueryParam is the corresponding parameter that DynamoDB expects in a query.

Use Case

A practical use case for adding custom mappings could be when you're using a newer feature of DynamoDB that isn't yet covered by DynamoBreeze's default mappings. By adding the necessary mapping, you ensure your application can take advantage of all DynamoDB features while maintaining the convenience of using DynamoBreeze.

Pagination

DynamoDB does not return all items in a single response; instead, it paginates the results. DynamoBreeze simplifies the pagination process, allowing you to easily navigate through your records. This is especially useful when dealing with large data sets.

Example Pagination

Imagine you want to retrieve all posts for a specific user, but due to the size of the data, DynamoDB paginates the results. Here's how you can handle pagination with DynamoBreeze:

Batch Retrieval with batchGet

When working with DynamoDB, there may be situations where you need to retrieve multiple items by their primary keys. The batchGet method provided by DynamoBreeze allows for the retrieval of multiple items across one or more tables in a single operation, which can be a more efficient alternative to issuing multiple GetItem requests.

In the following example, we are retrieving posts from multiple users stored in two different tables. We use batchGet to retrieve items from both the TableTwo and TableTwo using their primary keys.

Projection Expressions

In the realm of database operations, especially when dealing with extensive datasets, fetching only the necessary pieces of data is crucial for performance optimization. In the context of DynamoDB and hence DynamoBreeze, this selective retrieval of attributes is handled through what's known as "Projection Expressions."

ReturnConsumedCapacity

The ability to retrieve the capacity units consumed by a particular operation can be crucial for tracking usage and costs. The returnConsumedCapacity method is used to specify whether to return the capacity units consumed by an operation. Here's how it's used:

Dynamo Breeze Pattern Details

In the process of developing with Laravel, you may find yourself frequently interacting with the configuration details of DynamoDB tables. The dynamo-breeze:patterns Artisan command provides a clear overview of these details. This command fetches and neatly presents the access patterns for your DynamoDB tables, aiding in quick verification and reference. Below is a sample output illustrating the information structure:

Testing

composer test

Contribution

Contributions are welcome and will be fully credited. Please see CONTRIBUTING for details.

License

DynamoBreeze is open-sourced software licensed under the MIT license.

Contact

For general questions, brainstorming, and open-ended discussion, please use our GitHub Discussions. This is a great place to start socializing ideas, seek help from other community members, or discuss broader topics related to the project. Remember, a fresh perspective can be invaluable, and your insights might just spark the next big feature or improvement.