musonza / dynamodb-chat

Laravel DynamoDB Chat Library (WIP)

Table of Contents

Click to expand

• Introduction
• Installation
• Usage
  • Conversations
    • Create a Conversation
    • Create a direct conversation
    • Get / resolve a direct Conversation
    • Add participants to a Conversation
    • Remove participants from a Conversation
    • Update Conversation details
  • Messages
    • Send Message
    • Send Message with additional details
    • Delete Message
    • Mark Message as read
  • Reactions
• DynamoDB access patterns

Introduction

This is a simple chat library for DynamoDB. It is designed to be used with the AWS SDK for PHP. The package follows a single database design for DynamoDB. You can create a Chat application for your multiple entities.

Installation

Usage

Conversations (aka Rooms, Groups etc)

Create a Conversation

$conversation = Chat::conversation()
    ->setAttributes([
        'Subject' => 'Group 1',
        'Description' => 'My description',
    ])
    ->create();

Create a direct conversation

$conversation = Chat::conversation()
    ->setParticipants(['johnID', 'janeID'])
    ->setIsDirect(true)
    ->create();

Note: You will not be able to add additional participants to a direct conversation. Additionally, you can't remove a participant from a direct conversation.

Get / resolve a direct Conversation

You may want to get a direct conversation between two users. This is useful if you want to send a message to a user, but you don't know if they have a conversation with you already.

$conversation = Chat::conversation()
    ->getDirectConversation($participant1Id, $participant2Id);

Add participants to a Conversation

You can add participants to a conversation at any time. However, they will not be able to see messages sent before they were added.

Chat::addParticipants($conversationId, [
    'jamesID',
    'janeID',
    'johnID'
]);

Remove participants from a Conversation

You can remove participants from a conversation at any time. However, they will still be able to see messages sent before they were removed. Otherwise, they will not be able to see any new messages or send messages.

Chat::deleteParticipants(
    $conversationId, 
    ['user1', 'user2']
);

Update Conversation details

$updated = Chat::conversation($conversationId)
    ->setAttributes([
        'Subject' => $newSubject,
        'Description' => $description,
        // ... unchanged data
    ])
    ->update();

Messages

Send Message

Chat::messaging($conversationId)
    ->message($senderId, 'Hello')
    ->send();

Send Message with additional details

You can send a message with additional details. This is useful if you want to send a message with a link to a resource, or a file.

$data = [
    'images' => [
        [
            'file_name' => 'post_image.jpg',
            'file_url' => 'http://example.com/post_img.jpg',
        ],
        [
            'file_name' => 'post_image2.jpg',
            'file_url' => 'http://example.com/post_img2.jpg',
        ],
    ]
];

$message = Chat::messaging($conversationId)
    ->message($senderId, 'Hello', $data)
    ->send();

Delete Message

Deleting a message will remove it from the conversation for the specified user. The message will still be visible to other participants.

Chat::messaging($conversationId, $messageId)
    ->delete($recipientOwnerId);

Mark Message as read

Marking a message as read will remove the unread indicator for the specified user. The message will still be visible to other participants.

Chat::messaging($conversationId, $messageId)
    ->markAsRead($recipientOrOwnerId);

Reactions

Add reaction to a message

Chat::messaging($conversationId, $messageId)
    ->react('THUMBS_UP', $participantId);

Remove reaction from a message

Chat::messaging($conversationId, $messageId)
    ->unreact('THUMBS_UP', $participantId);

TODO

[] Reactions - like, dislike, laugh, etc

DynamoDB access patterns

Click to expand

Entity	PK	SK
Conversation	CONVERSATION#{ID}	CONVERSATION#{ID}
Participant	CONVERSATION#{ID}	PARTICIPANT#{ID}
Message	CONVERSATION#{ID}	MSG#{ID}

GSI1

Entity	GSI1PK	GSI1SK
Conversation
Participant	PARTICIPANT#{ID}	CONVERSATION#{ID}
Message	CONVERSATION#{ID}	MSG#{ID}

GSI2

Entity	GSI2PK	GSI2SK
Conversation
Participant
Message	PARTICIPANT#{senderId}	PARTICIPANT#{recipientId}