README

🚀 A blazingly fast, modern chat system for Laravel 12+

Built for real-time applications, infinite customization, and developer happiness

📦 Installation • ✨ Features • ⚙️ Quick Start • 📡 API Reference • 🤝 Contributing

✨ Features

💡 Perfect for: Chat applications, messaging systems, customer support platforms, team collaboration tools, and any real-time communication needs.

🚀 Installation

# Install the package
composer require faraztanveer/laravel-chat

# Run migrations
php artisan migrate

php artisan vendor:publish --provider="Faraztanveer\LaravelChat\LaravelChatServiceProvider" --tag=config

⚙️ Quick Start

1️⃣ Setup Your User Model

Add the HasChatChannels trait to your user model:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Faraztanveer\LaravelChat\Traits\HasChatChannels;

class User extends Authenticatable
{
    use HasChatChannels;
    
    // Your existing code...
}

2️⃣ Start Chatting!

That's it! Your application now has a fully functional chat system. The package provides RESTful API endpoints for all chat operations.

🎛️ Configuration

The package works seamlessly out of the box, but you can customize it to fit your needs.

Configuration file (config/laravel-chat.php):

<?php

return [
    // Your participant model (usually User model)
    'participant_model' => App\Models\User::class,
    
    // API route customization
    'route_prefix' => 'chat',                    // Routes: /api/chat/*
    'route_middleware' => ['auth:sanctum'],      // Authentication middleware
];

📡 API Reference

All endpoints are available under /api/{route_prefix} (default: /api/chat).

Example Usage

// Create or get a chat channel
const response = await fetch('/api/chat/channel', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer your-token'
    },
    body: JSON.stringify({
        participant_id: 2
    })
});

// Send a message
await fetch('/api/chat/message', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer your-token'
    },
    body: JSON.stringify({
        channel_id: 1,
        body: "Hello there!"
    })
});

🎨 Customization

Custom Display Names

Override the display name for chat participants:

class User extends Authenticatable
{
    use HasChatChannels;
    
    public function getChatDisplayName(): string
    {
        return $this->full_name ?? $this->name;
    }
}

Custom Participant Columns

Specify which columns to include in API responses:

class User extends Authenticatable
{
    use HasChatChannels;
    
    public function chatParticipantColumns(): array
    {
        return ['id', 'name', 'email', 'avatar_url'];
    }
}

Middleware Customization

You can customize authentication and authorization middleware in the configuration file:

// config/laravel-chat.php
return [
    'route_middleware' => ['auth:sanctum', 'verified', 'custom-middleware'],
];

🪝 Event Listeners & Extending Chat Actions

This package dispatches events when key chat actions occur, allowing you to react (broadcast, notify, etc) in your own app—without modifying package code.

Listening for Chat Events

You may listen for chat events by creating listeners with Artisan:

php artisan make:listener OnChatChannelCreated --event="\Faraztanveer\LaravelChat\Events\ChatChannelCreated"
php artisan make:listener OnChatMessageStored --event="\Faraztanveer\LaravelChat\Events\MessageStored"

When a chat channel is created or a message is stored, your listener's handle method will be called automatically with the corresponding Eloquent model.

Example: Message Stored Listener

<?php

namespace App\Listeners;

use Faraztanveer\LaravelChat\Events\MessageStored;
use Faraztanveer\LaravelChat\Http\Resources\MessageResource;
use Illuminate\Support\Facades\Log;

class OnChatMessageStored
{
    public function handle(MessageStored $event): void
    {
        // $event->message is the Message model instance
        // Log with a resource for consistent structure as used in API responses
        Log::debug('Chat message stored', [
            'event' => new MessageResource($event->message),
        ]);
        
        // Add any custom logic here (broadcast, notifications, etc)
    }
}

Example: Channel Created Listener

<?php

namespace App\Listeners;

use Faraztanveer\LaravelChat\Events\ChatChannelCreated;
use Faraztanveer\LaravelChat\Http\Resources\ChatChannelResource;
use Illuminate\Support\Facades\Log;

class OnChatChannelCreated
{
    public function handle(ChatChannelCreated $event): void
    {
        // $event->channel is the ChatChannel model instance
        Log::debug('Chat channel created', [
            'event' => new ChatChannelResource($event->channel),
        ]);
        
        // Custom logic here (notify users, update UI, etc)
    }
}

Resource Classes

The package provides resource classes (e.g. MessageResource, ChatChannelResource) which convert your models into the same format as your API responses.

You can use these in your listeners for logging, broadcasting, or passing structured data to your frontend—ensuring consistency between your API and event-driven features.

What You Get in Your Listener

• For message events: $event->message is a full Message Eloquent model.
• For channel events: $event->channel is a full ChatChannel Eloquent model.
• Use the provided resources for serialization if needed.

That's it! Your app can now respond to every chat action, with models and resources consistent with your APIs. For advanced event usage, see the Laravel Events documentation.

🤝 Contributing

We welcome contributions! Here's how you can help make Laravel Chat even better:

• 🐛 Found a bug? Open an issue
• 💡 Have an idea? Start a discussion
• 🔧 Want to contribute code? Check our contributing guide
• 📖 Improve documentation? Documentation PRs are always welcome!

🛡️ Security

Security is a top priority. If you discover any security-related issues, please email faraz.io@outlook.com instead of using the issue tracker.

See SECURITY.md for our security policy and vulnerability reporting process.

📋 Requirements

• PHP 8.2+
• Laravel 12.0+
• Database (MySQL, PostgreSQL, SQLite, SQL Server)

🗺️ Roadmap

• File attachment support
• Message reactions and emojis
• Message threading
• Advanced search functionality
• Message encryption
• Group chat management
• Message status indicators (sent, delivered, read)

📜 License

This package is open-sourced software licensed under the MIT License.

👨‍💻 Credits

• Faraz Tanveer - Creator & Maintainer
• All Contributors - Thank you! 🙏

Built with ❤️ for the Laravel community

⭐ Star this repository if it helped you!

🐛 Report Bug • 💡 Request Feature • 🐦 X