README

A UI-agnostic, transport-agnostic, polymorphic chat engine for Laravel.

Features

• Polymorphic Actors - Users, Teams, Bots, or any model can chat
• Thread Types - Direct, Group, Channel, Broadcast, Custom
• Rich Messages - Text, Image, Video, Audio, File, Location, Contact, Custom
• Attachments - Multi-file uploads, view-once media, direct request uploads
• Security - Thread locks, PIN protection, E2E verification codes
• Reactions - Emoji reactions via laravel-reactions integration
• Bookmarks - Save/bookmark messages via laravel-saveable integration
• Delivery Tracking - Delivered and read receipts
• Edit History - Immutable message versions (configurable)
• Soft/Hard Delete - Configurable deletion modes
• Authorization - Built-in policies for threads and messages
• Pipelines - Message processing (sanitize, mentions, URLs, profanity)
• Events - Domain events for all actions
• API Resources - Ready-to-use JSON transformations

Requirements

• PHP 8.2+
• Laravel 11.x or 12.x

Installation

composer require ritechoice23/laravel-chat-engine

Publish the config file:

php artisan vendor:publish --tag="chat-engine-config"

Run migrations:

php artisan migrate

Quick Start

Add the trait to your User model:

use Ritechoice23\ChatEngine\Traits\CanChat;

class User extends Authenticatable
{
    use CanChat;
}

Start chatting:

use Ritechoice23\ChatEngine\Facades\Chat;

// Create a thread
$thread = Chat::thread()->between($userA, $userB)->create();

// Send a message
$message = Chat::message()
    ->from($userA)
    ->to($thread)
    ->text('Hello!')
    ->send();

// React to message
$userB->react($message, '❤️');

// Bookmark message
$userB->saveItem($message);

// Mark as read
$message->markAsReadBy($userB);

File Uploads

Upload files directly from Laravel requests:

// Single file
Chat::message()
    ->from($request->user())
    ->to($thread)
    ->text('Check this out!')
    ->attachUpload($request->file('photo'))
    ->send();

// Multiple files
Chat::message()
    ->from($request->user())
    ->to($thread)
    ->attachUploads($request->file('attachments'))
    ->send();

// View-once (self-destructing)
Chat::message()
    ->from($request->user())
    ->to($thread)
    ->attachUploadViewOnce($request->file('secret'))
    ->send();

Message Types

// Text
Chat::message()->from($user)->to($thread)->text('Hello')->send();

// Image
Chat::message()->from($user)->to($thread)
    ->image('https://...', 'Caption')->send();

// Video
Chat::message()->from($user)->to($thread)
    ->video('https://...', 'thumb.jpg', 120)->send();

// File
Chat::message()->from($user)->to($thread)
    ->file('https://...', 'doc.pdf', 'application/pdf')->send();

// Location
Chat::message()->from($user)->to($thread)
    ->location(40.7128, -74.0060, 'NYC')->send();

// Contact
Chat::message()->from($user)->to($thread)
    ->contact('John Doe', '+1234567890', 'john@example.com')->send();

Thread Types

// Direct (1-on-1, automatically deduplicated)
Chat::thread()->between($userA, $userB)->create();

// Group
Chat::thread()->group('Team Chat')->participants([$u1, $u2, $u3])->create();

// Channel
Chat::thread()->channel('announcements')->create();

// Broadcast
Chat::thread()->broadcast('System Updates')->create();

Documentation

See /docs for complete documentation:

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

If you discover a security vulnerability, please send an email to daramolatunde23@gmail.com. All security vulnerabilities will be promptly addressed.

Credits

• Daramola Babatunde Ebenezer
• All Contributors

License

The MIT License (MIT). Please see License File for more information.