PHPackages                             zedmagdy/filament-chat - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. zedmagdy/filament-chat

ActiveLibrary

zedmagdy/filament-chat
======================

A filament package for creating chat interfaces in your Laravel applications.

v0.4.0(1mo ago)14↓100%[2 PRs](https://github.com/ZED-Magdy/filament-chat/pulls)MITPHPPHP ^8.3CI passing

Since Mar 17Pushed 1mo agoCompare

[ Source](https://github.com/ZED-Magdy/filament-chat)[ Packagist](https://packagist.org/packages/zedmagdy/filament-chat)[ Docs](https://github.com/ZED-Magdy/filament-chat)[ GitHub Sponsors](https://github.com/ZED-Magdy)[ RSS](/packages/zedmagdy-filament-chat/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (15)Versions (6)Used By (0)

Filament Chat
=============

[](#filament-chat)

[![Latest Version on Packagist](https://camo.githubusercontent.com/4494126f232f9f6641c561b96ba59d0401c29420d09ba070325fd5dc2476bee6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7a65646d616764792f66696c616d656e742d636861742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/zedmagdy/filament-chat)[![GitHub Tests Action Status](https://camo.githubusercontent.com/e790c4e1bd782e7e39c0e95dffda8fb2447a6e802bfa52862a560500260aedaa/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f5a45442d4d616764792f66696c616d656e742d636861742f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/ZED-Magdy/filament-chat/actions?query=workflow%3Arun-tests+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/38bb2522e7fd704d544ef7d4f0b9be383dfa256e5b1efd634ea28837b131271f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7a65646d616764792f66696c616d656e742d636861742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/zedmagdy/filament-chat)

A chat plugin for Filament v4 that supports configurable chat sources, one-to-one and group conversations, text and file attachments (via Spatie Media Library), read/unread tracking, search, and real-time updates via polling or broadcasting (Reverb/Pusher).

Requirements
------------

[](#requirements)

- PHP ^8.3
- Laravel ^11.0 or ^12.0
- Filament ^4.3.1 or ^5.0
- Spatie Media Library (installed automatically)

Installation
------------

[](#installation)

Install via Composer:

```
composer require zedmagdy/filament-chat
```

Publish and run the migrations:

```
php artisan vendor:publish --tag="filament-chat-migrations"
php artisan migrate
```

If you haven't already, publish the Spatie Media Library migration as well:

```
php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="medialibrary-migrations"
php artisan migrate
```

Optionally publish the config:

```
php artisan vendor:publish --tag="filament-chat-config"
```

Optionally publish the views for customization:

```
php artisan vendor:publish --tag="filament-chat-views"
```

Full Integration Example
------------------------

[](#full-integration-example)

### 1. Add the `HasChats` trait to your User model

[](#1-add-the-haschats-trait-to-your-user-model)

```
namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use ZEDMagdy\FilamentChat\Traits\HasChats;

class User extends Authenticatable
{
    use HasChats;

    // ...
}
```

This gives your User model these relationships:

- `chatParticipations()` - all chat participations
- `conversations()` - all conversations the user is part of
- `sentMessages()` - all messages sent by the user

### 2. Create a Chat Source

[](#2-create-a-chat-source)

The quickest way is with the Artisan command:

```
# Interactive (prompts for name and model)
php artisan make:chat-source

# Non-interactive
php artisan make:chat-source Staff --model=User
```

This generates two files:

- `app/Chat/StaffChatSource.php` — the chat source class
- `app/Filament/Pages/StaffChatPage.php` — the Filament page

Then skip to [step 4](#4-register-the-plugin-in-your-panel) to register it.

#### Manual setup

[](#manual-setup)

A chat source defines a category of chat (e.g. staff-to-staff, patient support). Create one class per source:

```
namespace App\Chat;

use App\Filament\Pages\StaffChatPage;
use App\Models\User;
use Illuminate\Database\Eloquent\Builder;
use ZEDMagdy\FilamentChat\ChatSource;

class StaffChatSource extends ChatSource
{
    public function getKey(): string
    {
        return 'staff';
    }

    public function getLabel(): string
    {
        return 'Staff Chat';
    }

    public function getIcon(): string
    {
        return 'heroicon-o-chat-bubble-left-right';
    }

    public function getParticipantModel(): string
    {
        return User::class;
    }

    public function getPageClass(): string
    {
        return StaffChatPage::class;
    }

    // Optional: filter which users can be added to new conversations
    public function getAvailableParticipantsQuery(): Builder
    {
        return User::query()->where('role', 'staff');
    }

    // Optional: allow users to create new conversations (default: true)
    public function allowsNewConversations(): bool
    {
        return true;
    }

    // Optional: enable group chats for this source (default: false)
    public function allowsGroupChats(): bool
    {
        return true;
    }

    // Optional: customize navigation
    public function getNavigationGroup(): ?string
    {
        return 'Communication';
    }

    public function getNavigationSort(): ?int
    {
        return 1;
    }

    // Optional: customize how participant names are displayed
    public function getParticipantDisplayName(\Illuminate\Database\Eloquent\Model $participant): string
    {
        return $participant->name;
    }

    // Optional: provide avatar URLs
    public function getParticipantAvatarUrl(\Illuminate\Database\Eloquent\Model $participant): ?string
    {
        return $participant->avatar_url;
    }
}
```

### 3. Create a Chat Page

[](#3-create-a-chat-page)

Each chat source needs a thin Filament page class:

```
namespace App\Filament\Pages;

use ZEDMagdy\FilamentChat\Pages\ChatSourcePage;

class StaffChatPage extends ChatSourcePage
{
    protected static string $chatSourceKey = 'staff';
}
```

That's it. The page inherits its navigation label, icon, group, sort, and slug from the chat source.

### 4. Register the Plugin in your Panel

[](#4-register-the-plugin-in-your-panel)

```
namespace App\Providers\Filament;

use App\Chat\StaffChatSource;
use Filament\Panel;
use Filament\PanelProvider;
use ZEDMagdy\FilamentChat\FilamentChatPlugin;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->default()
            ->id('admin')
            ->path('admin')
            // ... other config
            ->plugin(
                FilamentChatPlugin::make()
                    ->sources([
                        StaffChatSource::class,
                    ])
            );
    }
}
```

### 5. Multiple Chat Sources

[](#5-multiple-chat-sources)

You can register multiple sources for different chat contexts:

```
// app/Chat/PatientChatSource.php
namespace App\Chat;

use App\Filament\Pages\PatientChatPage;
use App\Models\Patient;
use ZEDMagdy\FilamentChat\ChatSource;

class PatientChatSource extends ChatSource
{
    public function getKey(): string
    {
        return 'patient';
    }

    public function getLabel(): string
    {
        return 'Patient Messages';
    }

    public function getIcon(): string
    {
        return 'heroicon-o-heart';
    }

    public function getParticipantModel(): string
    {
        return Patient::class; // any model with HasChats trait
    }

    public function getPageClass(): string
    {
        return PatientChatPage::class;
    }
}
```

```
// app/Filament/Pages/PatientChatPage.php
namespace App\Filament\Pages;

use ZEDMagdy\FilamentChat\Pages\ChatSourcePage;

class PatientChatPage extends ChatSourcePage
{
    protected static string $chatSourceKey = 'patient';
}
```

Register both in your panel:

```
->plugin(
    FilamentChatPlugin::make()
        ->sources([
            StaffChatSource::class,
            PatientChatSource::class,
        ])
)
```

### 6. Creating Conversations from the UI

[](#6-creating-conversations-from-the-ui)

Users can start new conversations by clicking the **+** button in the chat sidebar. This opens a modal where they select a participant (or multiple for group chats).

**Behavior:**

- **Direct chats:** If a conversation already exists between the two users in the same source, it opens the existing one instead of creating a duplicate.
- **Group chats:** Only available if `allowsGroupChats()` returns `true`. Users provide a group name and select multiple participants.
- **Participant list:** Filtered by `getAvailableParticipantsQuery()` — the current user is excluded automatically.

**Disabling conversation creation:**

Override `allowsNewConversations()` in your chat source to hide the button:

```
public function allowsNewConversations(): bool
{
    return false; // Users can only see existing conversations
}
```

This is useful for system-managed chats where conversations are created programmatically (e.g. a support ticket system that auto-creates a chat per ticket).

### 7. Creating Conversations Programmatically

[](#7-creating-conversations-programmatically)

```
use ZEDMagdy\FilamentChat\Models\Conversation;
use ZEDMagdy\FilamentChat\Models\Participant;
use ZEDMagdy\FilamentChat\Models\Message;

// Create a direct conversation
$conversation = Conversation::create([
    'source' => 'staff',
    'type' => 'direct',
]);

// Add participants
Participant::create([
    'conversation_id' => $conversation->id,
    'participantable_id' => $user1->id,
    'participantable_type' => $user1->getMorphClass(),
]);

Participant::create([
    'conversation_id' => $conversation->id,
    'participantable_id' => $user2->id,
    'participantable_type' => $user2->getMorphClass(),
]);

// Send a message
$message = Message::create([
    'conversation_id' => $conversation->id,
    'senderable_id' => $user1->id,
    'senderable_type' => $user1->getMorphClass(),
    'body' => 'Hello!',
]);

// Create a group conversation
$group = Conversation::create([
    'source' => 'staff',
    'type' => 'group',
    'name' => 'Project Team',
]);

// Send a system message (no sender)
Message::create([
    'conversation_id' => $group->id,
    'body' => 'User1 created the group',
]);
```

### 8. Working with Attachments

[](#8-working-with-attachments)

The `Message` model uses Spatie Media Library. Attachments are stored in the `chat-attachments` media collection:

```
$message = Message::create([
    'conversation_id' => $conversation->id,
    'senderable_id' => $user->id,
    'senderable_type' => $user->getMorphClass(),
    'body' => 'Check out this file',
]);

// Add an attachment
$message->addMedia($pathToFile)
    ->toMediaCollection('chat-attachments');

// Get attachments
$message->getMedia('chat-attachments');
```

In the UI, the `MessageInput` Livewire component uses Filament's `SpatieMediaLibraryFileUpload` for seamless file uploads.

Real-time Updates
-----------------

[](#real-time-updates)

### Polling (default)

[](#polling-default)

Out of the box, the chat window polls for new messages. Configure the interval in your `.env` or config:

```
FILAMENT_CHAT_REALTIME_MODE=polling
```

```
// config/filament-chat.php
'realtime' => [
    'mode' => 'polling',
    'polling_interval' => '5s',
],
```

### Broadcasting (Reverb / Pusher)

[](#broadcasting-reverb--pusher)

For real-time updates via WebSockets:

```
FILAMENT_CHAT_REALTIME_MODE=broadcasting
```

The package broadcasts `MessageSent` and `MessagesRead` events on private channels (`chat.conversation.{id}`). Channel authorization is handled automatically - only conversation participants can listen.

Make sure your Laravel broadcasting is configured (Reverb, Pusher, etc.) and that your frontend includes the Echo setup.

Configuration
-------------

[](#configuration)

```
// config/filament-chat.php
return [
    'table_prefix' => 'chat_',

    'realtime' => [
        'mode' => env('FILAMENT_CHAT_REALTIME_MODE', 'polling'),
        'polling_interval' => '5s',
    ],

    'attachments' => [
        'disk' => env('FILAMENT_CHAT_DISK', 'public'),
        'collection' => 'chat-attachments',
        'max_files' => 4,
        'max_file_size' => 10240, // KB
        'accepted_types' => [
            'image/jpeg', 'image/png', 'image/gif', 'image/webp',
            'application/pdf',
            'application/vnd.ms-excel',
            'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
            'text/csv',
        ],
    ],

    'messages_per_page' => 50,
    'conversations_per_page' => 25,

    'theme' => [
        'sent_bg' => 'primary-500',
        'received_bg' => 'gray-100',
        'sent_text' => 'white',
        'received_text' => 'gray-900',
    ],

    // Override with your own model classes
    'models' => [
        'conversation' => \ZEDMagdy\FilamentChat\Models\Conversation::class,
        'message' => \ZEDMagdy\FilamentChat\Models\Message::class,
        'participant' => \ZEDMagdy\FilamentChat\Models\Participant::class,
    ],
];
```

### Custom Models

[](#custom-models)

You can extend the built-in models and register them in the config:

```
namespace App\Models;

use ZEDMagdy\FilamentChat\Models\Conversation as BaseConversation;

class Conversation extends BaseConversation
{
    // Add your custom logic
}
```

```
// config/filament-chat.php
'models' => [
    'conversation' => \App\Models\Conversation::class,
],
```

Events
------

[](#events)

The package dispatches the following events:

EventBroadcastsDescription`MessageSent`YesFired when a message is sent. Broadcasts on `chat.conversation.{id}`.`ConversationCreated`NoFired when a new conversation is created.`MessagesRead`YesFired when a user reads messages. Broadcasts read receipts.Listen to them in your `EventServiceProvider` or with `Event::listen()`:

```
use ZEDMagdy\FilamentChat\Events\MessageSent;

Event::listen(MessageSent::class, function (MessageSent $event) {
    // Send a notification, update counters, etc.
    $event->message;
    $event->message->conversation;
    $event->message->senderable;
});
```

Testing
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [ZED-Magdy](https://github.com/ZED-Magdy)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

38

—

LowBetter than 84% of packages

Maintenance90

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 92.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

4

Last Release

51d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/b32df6c1ee21b76b908877053d87fb9d63aba06b089f47a81bfe808302bc00b3?d=identicon)[ZED-Magdy](/maintainers/ZED-Magdy)

---

Top Contributors

[![ZED-Magdy](https://avatars.githubusercontent.com/u/43310796?v=4)](https://github.com/ZED-Magdy "ZED-Magdy (12 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")

---

Tags

laravelchatfilament

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/zedmagdy-filament-chat/health.svg)

```
[![Health](https://phpackages.com/badges/zedmagdy-filament-chat/health.svg)](https://phpackages.com/packages/zedmagdy-filament-chat)
```

###  Alternatives

[bezhansalleh/filament-shield

Filament support for `spatie/laravel-permission`.

2.8k2.9M88](/packages/bezhansalleh-filament-shield)[pboivin/filament-peek

Full-screen page preview modal for Filament

253319.6k12](/packages/pboivin-filament-peek)[croustibat/filament-jobs-monitor

Background Jobs monitoring like Horizon for all drivers for FilamentPHP

254255.2k6](/packages/croustibat-filament-jobs-monitor)[dotswan/filament-map-picker

Easily pick and retrieve geo-coordinates using a map-based interface in your Filament applications.

124139.3k2](/packages/dotswan-filament-map-picker)[stephenjude/filament-jetstream

A Laravel starter kit built with Filament inspired by Jetstream.

17554.3k2](/packages/stephenjude-filament-jetstream)[creagia/filament-code-field

A Filamentphp input field to edit or view code data.

58289.3k3](/packages/creagia-filament-code-field)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)