adultdate/filament-wirechat

A Laravel Livewire messaging app for teams with private chats and group conversations.

dev-master 2025-08-30 05:44 UTC

Requires

• php: ^8.1|^8.2|^8.3|^8.4
• filament/filament: ^4.0
• laravel/framework: ^10.0|^11.0|^12.0
• livewire/livewire: ^3.2.3

Requires (Dev)

• christophrumpel/missing-livewire-assertions: ^2.8
• larastan/larastan: ^2.0|^3.0
• laravel/pint: ^1.18
• orchestra/testbench: ^8.24|^9.0|^10.0
• pestphp/pest: ^2.34|^3.0.0
• pestphp/pest-plugin-laravel: ^2.4|^3.0.0

MIT

• Namu Makwembo

README

Filament-WireChat is a comprehensive plugin designed to seamlessly integrate real-time messaging capabilities into your Filament v4 application. This plugin enhances user engagement by providing a robust chat interface directly within your Filament dashboard.

Features

• Real-Time Messaging: Facilitates instant communication between users with WebSocket support
• Private Conversations: Allows users to initiate one-on-one chats with privacy controls
• Group Chats: Enables the creation of group conversations for team collaborations
• Media Attachments: Supports sharing images, videos, and documents
• Dashboard Widget: Live chat widget integrated directly into Filament dashboard
• Message Notifications: Real-time notifications for incoming messages
• Admin Interface: Complete admin panel for managing conversations and messages
• Customizable Theme: Dark mode support and branding customization
• Broadcasting: Laravel Echo integration for real-time updates
• Permissions: Granular permission system for chat management

Requirements

• PHP: 8.1 or higher
• Laravel: 10.0, 11.0, or 12.0
• Filament: 3.2 or higher
• Livewire: 3.2.3 or higher
• Database: MySQL, PostgreSQL, SQLite, or SQL Server

Optional Requirements

• Redis: For enhanced broadcasting performance
• Pusher: For WebSocket broadcasting
• Laravel Echo: For real-time frontend updates

Installation

Step 1: Install via Composer

composer require adultdate/filament-wirechat

Step 2: Publish Configuration

php artisan vendor:publish --provider="Adultdate\WireChat\WireChatServiceProvider" --tag="wirechat-config"

Step 3: Publish Migrations

php artisan vendor:publish --provider="Adultdate\WireChat\WireChatServiceProvider" --tag="wirechat-migrations"

Step 4: Run Migrations

php artisan migrate

Step 5: Publish Assets (Optional)

php artisan vendor:publish --provider="Adultdate\WireChat\WireChatServiceProvider" --tag="wirechat-assets"

Step 6: Register Plugin in Filament

In your app/Providers/Filament/AdminPanelProvider.php:

<?php

namespace App\Providers\Filament;

use Filament\Panel;
use Filament\PanelProvider;
use Adultdate\WireChat\WireChatPlugin;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            // ... your existing panel configuration
            ->plugin(WireChatPlugin::make());
    }
}

Configuration

Basic Configuration

After publishing the configuration file, you can find it at config/wirechat.php. Here are the key configuration options:

<?php

return [
    /*
    |--------------------------------------------------------------------------
    | User Model
    |--------------------------------------------------------------------------
    */
    'user_model' => App\Models\User::class,

    /*
    |--------------------------------------------------------------------------
    | Table Prefix
    |--------------------------------------------------------------------------
    */
    'table_prefix' => 'wire_',

    /*
    |--------------------------------------------------------------------------
    | Broadcasting Configuration
    |--------------------------------------------------------------------------
    */
    'broadcasting' => [
        'messages_queue' => 'messages',
        'notifications_queue' => 'default',
    ],

    /*
    |--------------------------------------------------------------------------
    | Theme Color
    |--------------------------------------------------------------------------
    */
    'color' => '#a855f7',

    /*
    |--------------------------------------------------------------------------
    | Routes Configuration
    |--------------------------------------------------------------------------
    */
    'routes' => [
        'prefix' => 'chats',
        'middleware' => ['web', 'auth:web'],
        'guards' => ['web'],
    ],
];

Filament Integration Configuration

'filament' => [
    'enabled' => true,
    'navigation_group' => 'WireChat',

    'resources' => [
        'conversations' => true,
        'messages' => true,
        'participants' => true,
        'groups' => true,
    ],

    'pages' => [
        'dashboard' => true,
        'chat_interface' => true,
        'settings' => true,
    ],

    'widgets' => [
        'stats' => true,
        'recent_chats' => true,
        'active_conversations' => true,
        'live_chat' => true,
    ],

    'permissions' => [
        'view_conversations' => 'view conversations',
        'create_conversations' => 'create conversations',
        'edit_conversations' => 'edit conversations',
        'delete_conversations' => 'delete conversations',
        // ... more permissions
    ],
],

Broadcasting Setup

Using Pusher

1. Install Pusher PHP SDK:

composer require pusher/pusher-php-server

1. Configure broadcasting in config/broadcasting.php:

'connections' => [
    'pusher' => [
        'driver' => 'pusher',
        'key' => env('PUSHER_APP_KEY'),
        'secret' => env('PUSHER_APP_SECRET'),
        'app_id' => env('PUSHER_APP_ID'),
        'options' => [
            'cluster' => env('PUSHER_APP_CLUSTER'),
            'encrypted' => true,
        ],
    ],
],

1. Set your environment variables in .env:

BROADCAST_DRIVER=pusher
PUSHER_APP_ID=your_app_id
PUSHER_APP_KEY=your_app_key
PUSHER_APP_SECRET=your_app_secret
PUSHER_APP_CLUSTER=your_cluster

Using Redis

1. Install Predis:

composer require predis/predis

1. Configure Redis in config/database.php:

'redis' => [
    'client' => env('REDIS_CLIENT', 'predis'),
    'options' => [
        'cluster' => env('REDIS_CLUSTER', 'redis'),
    ],
    'default' => [
        'url' => env('REDIS_URL'),
        'host' => env('REDIS_HOST', '127.0.0.1'),
        'password' => env('REDIS_PASSWORD'),
        'port' => env('REDIS_PORT', '6379'),
        'database' => env('REDIS_DB', '0'),
    ],
],

Frontend Setup

Laravel Echo Setup

1. Install Laravel Echo and Pusher JS:

npm install --save-dev laravel-echo pusher-js

1. Configure Echo in resources/js/bootstrap.js:

import Echo from 'laravel-echo';
import Pusher from 'pusher-js';

window.Pusher = Pusher;

window.Echo = new Echo({
    broadcaster: 'pusher',
    key: process.env.MIX_PUSHER_APP_KEY,
    cluster: process.env.MIX_PUSHER_APP_CLUSTER,
    encrypted: true,
});

1. Build assets:

npm run dev
# or
npm run build

Usage

Basic Usage

Creating Conversations

use Adultdate\WireChat\Models\Conversation;

// Create a private conversation
$conversation = Conversation::create([
    'topic' => 'Project Discussion',
    'is_direct' => false,
    'created_by' => auth()->id(),
]);

// Add participants
$conversation->participants()->create([
    'participantable_id' => $userId,
    'participantable_type' => App\Models\User::class,
    'role' => 'member',
]);

Sending Messages

use Adultdate\WireChat\Models\Message;

// Send a message
$message = Message::create([
    'conversation_id' => $conversation->id,
    'sender_id' => auth()->id(),
    'sender_type' => get_class(auth()->user()),
    'body' => 'Hello, this is a test message!',
    'type' => 'text',
]);

Using the Chat Interface

The WireChat interface is automatically available in your Filament admin panel under the "WireChat" navigation group.

Advanced Usage

Custom User Model

If you're using a custom user model, update the configuration:

// config/wirechat.php
'user_model' => App\Models\CustomUser::class,

Make sure your custom user model implements the Chatable trait:

<?php

namespace App\Models;

use Adultdate\WireChat\Traits\Chatable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class CustomUser extends Authenticatable
{
    use Chatable;

    // ... your model code
}

Custom Message Types

You can create custom message types by extending the Message model:

<?php

namespace App\Models;

use Adultdate\WireChat\Models\Message as BaseMessage;

class CustomMessage extends BaseMessage
{
    protected static function booted()
    {
        static::creating(function ($message) {
            // Custom logic for message creation
        });
    }
}

File Attachments

Configure file attachments in the configuration:

// config/wirechat.php
'attachments' => [
    'storage_folder' => 'wirechat/attachments',
    'storage_disk' => 'public',
    'max_uploads' => 10,
    'media_mimes' => ['png', 'jpg', 'jpeg', 'gif', 'mov', 'mp4'],
    'media_max_upload_size' => 12288, // 12MB
    'file_mimes' => ['zip', 'rar', 'txt', 'pdf'],
    'file_max_upload_size' => 12288, // 12MB
],

API Reference

Models

Conversation

$conversation->participants() // Get participants
$conversation->messages()     // Get messages
$conversation->lastMessage    // Get last message
$conversation->owner          // Get conversation owner

Message

$message->conversation  // Get conversation
$message->sender        // Get sender
$message->attachments   // Get attachments
$message->replies       // Get replies

Participant

$participant->conversation     // Get conversation
$participant->participantable  // Get the participant model (User, etc.)
$participant->role            // Get participant role

Events

MessageCreated

Fired when a new message is created.

use Adultdate\WireChat\Events\MessageCreated;

$message = Message::create([...]);

event(new MessageCreated($message));

MessageDeleted

Fired when a message is deleted.

MessageUpdated

Fired when a message is updated.

Listeners

SendFilamentNotification

Sends Filament notifications for new messages.

Facades

WireChat

use Adultdate\WireChat\Facades\WireChat;

WireChat::messagesQueue();     // Get messages queue name
WireChat::notificationsQueue(); // Get notifications queue name

Testing

Running Tests

# Run all tests
composer run-script test

# Run specific test
./vendor/bin/pest tests/Feature/Chat/

# Run with coverage
./vendor/bin/pest --coverage

Testing Commands

# Test notifications
composer run-script test:notifications

# Test admin notifications
composer run-script test:admin-notifications

Troubleshooting

Common Issues

Broadcasting Not Working

1. Ensure your broadcasting configuration is correct
2. Check that your queue worker is running:

php artisan queue:work

1. Verify your .env broadcasting settings

Permission Issues

1. Check your user model's permissions
2. Ensure proper gates and policies are set up
3. Verify Filament shield configuration

File Upload Issues

1. Check storage permissions
2. Verify upload configuration in config/wirechat.php
3. Ensure proper disk configuration

Real-time Updates Not Working

1. Verify Laravel Echo setup
2. Check WebSocket connection
3. Ensure proper broadcasting routes are registered

Debug Commands

# Check WireChat status
php artisan wirechat:status

# Clear WireChat cache
php artisan wirechat:clear-cache

# Test broadcasting connection
php artisan wirechat:test-broadcasting

Contributing

We welcome contributions! Please see our contributing guidelines for details.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Security

If you discover any security issues, please email [e-mail]/adultdate instead of using the issue tracker.

License

This package is open-source software licensed under the MIT license.

Support

For support, please:

1. Check the documentation
2. Search existing issues
3. Create a new issue if needed

Changelog

See CHANGELOG.md for recent changes and updates.

Built with ❤️ by AdultDate