Filament Chat Laravel Package

Getting Started

Minimal Setup

1. Installation (updated for v0.8.0 compatibility):

   composer require zedmagdy/filament-chat:^0.8.0
   php artisan vendor:publish --tag="filament-chat-migrations"
   php artisan migrate
   

   • Verify config/filament-chat.php exists (published automatically).

2. First Use Case:

   • Register the plugin in app/Providers/Filament/AdminPanelProvider.php:

     public function panel(Panel $panel): Panel
     {
         return $panel
             ->plugins([
                 \ZedMagdy\FilamentChat\FilamentChatPlugin::make(),
             ]);
     }
     

   • Access the chat via the Filament sidebar (default location).

3. Quick Configuration:

   • Define a default chat source (now supports all_messages):

     'default_source' => 'all_messages', // New option for global chat
     

   • Ensure the source model implements ZedMagdy\FilamentChat\Contracts\ChatSource.

Implementation Patterns

Core Workflows

1. Chat Sources (updated):

   • New all_messages source for global conversations:

     'sources' => [
         'users' => \App\Models\User::class,
         'teams' => \App\Models\Team::class,
         'all_messages' => \ZedMagdy\FilamentChat\Sources\AllMessagesSource::class, // New
     ],
     

   • Extend ChatSource trait for custom models:

     use ZedMagdy\FilamentChat\Contracts\ChatSource;
     
     class User extends Authenticatable implements ChatSource
     {
         use \ZedMagdy\FilamentChat\Traits\ChatSource;
     }
     

2. Media-Only Messages (new):

   • Send messages with only media (no text content):

     $message = \ZedMagdy\FilamentChat\Models\Message::create([
         'conversation_id' => $conversation->id,
         'sender_id' => auth()->id(),
         'sender_type' => 'users',
         'content' => null, // Empty content for media-only
     ]);
     $message->addMedia($file)->toMediaCollection('attachments');
     

   • UI automatically handles rendering media-only messages.

3. Conversations (unchanged):

   • One-to-One: Automatically created for user interactions.
   • Group: Manually create via UI or API:

     $conversation = \ZedMagdy\FilamentChat\Models\Conversation::createGroup([
         'name' => 'Project Team',
         'source_type' => 'teams',
         'source_id' => 1,
     ]);
     

4. Real-Time Updates (unchanged):

   • Enable broadcasting in config/filament-chat.php:

     'broadcasting' => [
         'driver' => 'reverb',
         'options' => [
             'key' => env('PUSHER_APP_KEY'),
         ],
     ],
     

5. Search and Filtering (updated):

   • Search now includes all_messages source:

     $conversations = \ZedMagdy\FilamentChat\Models\Conversation::search('project')
         ->whereNot('source_type', 'all_messages') // Exclude global if needed
         ->get();
     

Integration Tips

• Filament Resources: Link chat to a resource via custom action or tab (unchanged):

  public static function getTabs(PostResource $resource): array
  {
      return [
          'chat' => ChatTab::make(),
      ];
  }
  

• API Endpoints: Use Filament’s API to fetch conversations/messages (unchanged):

  Route::get('/api/chat/conversations', [ChatController::class, 'index']);
  

• Custom UI: Override Blade views in resources/views/vendor/filament-chat/ (unchanged).

Gotchas and Tips

Pitfalls

1. Media Library Compatibility (updated):

   • Package now requires spatie/laravel-media-library-plugin (not standalone).
   • Fix: Install the plugin:

     composer require spatie/laravel-media-library-plugin
     php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="medialibrary-config"
     php artisan migrate
     

2. Media-Only Messages (new):

   • Ensure content is null for media-only messages (not empty string).
   • Debug: Check storage/logs/laravel.log for media upload validation errors.

3. Broadcasting Issues (unchanged):

   • Verify APP_URL for Reverb/Pusher webhook validation.

4. Database Indexes (unchanged):

   • Add indexes for large-scale apps:

     ALTER TABLE conversations ADD INDEX source_type_source_id_idx (source_type, source_id);
     

5. Real-Time Polling (unchanged):

   • Disable polling if unused:

     'polling' => [
         'enabled' => false,
     ],
     

Debugging

1. Log Events (unchanged): Enable debug mode:

   'debug' => env('APP_DEBUG', false),
   

2. Common Errors (updated):

   • Class not found: Ensure spatie/laravel-media-library-plugin is installed.
   • Media upload failures: Verify public_path('storage') is writable.

3. Broadcast Debugging (unchanged): Test events in Tinker:

   php artisan tinker
   >>> event(new \ZedMagdy\FilamentChat\Events\MessageSent($message));
   

Extension Points

1. Custom Message Types (updated): Handle media-only messages in events:

   \ZedMagdy\FilamentChat\Events\MessageSent::listen(function ($event) {
       if (empty($event->message->content)) {
           // Media-only message logic
       }
   });
   

2. Chat Widget (unchanged): Embed chat in non-Filament views:

   ChatWidget::make()
       ->source('users')
       ->conversation($conversation)
       ->render();
   

3. API Extensions (unchanged): Create custom routes for media-only messages:

   Route::post('/api/chat/media-messages', [ChatController::class, 'storeMedia']);
   

4. Theming (unchanged): Override Tailwind classes in resources/css/filament-chat.css.

5. Localization (unchanged): Publish language files:

   php artisan vendor:publish --tag="filament-chat-lang"