Filament Chat Bubbles Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aaix/filament-chat-bubbles
   

   Publish the config and migrations:

   php artisan vendor:publish --provider="Aaix\FilamentChatBubbles\FilamentChatBubblesServiceProvider" --tag="config"
   php artisan vendor:publish --provider="Aaix\FilamentChatBubbles\FilamentChatBubblesServiceProvider" --tag="migrations"
   php artisan migrate
   

2. Configure Laravel Echo Ensure your config/filament-chat-bubbles.php is set up with your broadcasting driver (e.g., Pusher, Laravel WebSockets). Example:

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

3. Register the Plugin Add the plugin to your Filament admin panel in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Aaix\FilamentChatBubbles\FilamentChatBubblesPlugin::make(),
           ]);
   }
   

4. First Use Case: Send a Test Message Use Tinker to create a test user and message:

   php artisan tinker
   

   $user = \App\Models\User::first();
   $message = \Aaix\FilamentChatBubbles\Models\Message::create([
       'user_id' => $user->id,
       'content' => 'Hello from Filament Chat Bubbles!',
       'is_read' => false,
   ]);
   

Implementation Patterns

Core Workflows

1. Real-Time Messaging

• Sending Messages Use the sendMessage helper or manually create a Message model. Trigger a broadcast event:

  use Aaix\FilamentChatBubbles\Events\MessageSent;
  
  event(new MessageSent($message));
  

  Or use the provided facade:

  \Aaix\FilamentChatBubbles\Facades\FilamentChatBubbles::sendMessage($userId, 'Hello!');
  

• Listening for Messages Subscribe to the message-sent channel in your frontend JavaScript (handled automatically by the package if configured correctly). No manual JS setup is needed beyond Laravel Echo initialization.

2. File Sharing

• Attach files to messages using the attachments relationship:

  $message->attachments()->attach([
      ['fileable_id' => $file->id, 'fileable_type' => \App\Models\File::class],
  ]);
  

• Files must implement the HasAttachments trait or use a polymorphic relationship.

3. Presence Tracking

• Use the is_online column in the users table (auto-synced via the Presence model). Trigger presence updates:

  \Aaix\FilamentChatBubbles\Facades\FilamentChatBubbles::setUserPresence($userId, true);
  

• Listen for user-presence-updated events in your frontend.

4. Customizing Bubbles

• Override the bubble view by publishing the views:

  php artisan vendor:publish --provider="Aaix\FilamentChatBubbles\FilamentChatBubblesServiceProvider" --tag="views"
  

• Modify resources/views/vendor/filament-chat-bubbles/bubble.blade.php to change styling or content.

Integration Tips

Laravel Echo Setup

Ensure your resources/js/bootstrap.js includes Echo:

import Echo from 'laravel-echo';

window.Pusher = require('pusher-js');

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

Filament Panel Integration

• Positioning Bubbles: Use the position config option in filament-chat-bubbles.php to place bubbles (e.g., top-right, bottom-left).
• Accessing Chat: Bubbles appear by default. Clicking a bubble opens the slide-over modal. Use the chatBubbles widget in your Filament panel:

  use Aaix\FilamentChatBubbles\Widgets\ChatBubbles;
  
  public function widgets(): array
  {
      return [
          ChatBubbles::make(),
      ];
  }
  

API Endpoints

The package includes API routes for messages and files. Extend them in routes/api.php:

Route::middleware('auth:sanctum')->group(function () {
    require __DIR__.'/filament-chat-bubbles.php';
});

Gotchas and Tips

Pitfalls

1. Broadcasting Driver Mismatch

   • If messages aren’t appearing in real-time, verify your broadcasting driver (e.g., Pusher, Redis) is correctly configured in .env and config/broadcasting.php.
   • Test with php artisan queue:work if using Redis.

2. CORS Issues

   • Ensure your broadcasting service (e.g., Pusher) allows requests from your Filament panel’s domain. Add to config/cors.php:

     'paths' => ['api/*', 'broadcasting/auth', 'echo/*'],
     'allowed_methods' => ['*'],
     'allowed_origins' => ['*'], // Replace with your panel's URL in production
     

3. File Attachments Not Showing

   • Ensure files are stored in a location accessible via the Storage facade (e.g., public or s3). Use the url method:

     $file->url(); // Returns the accessible URL
     

4. Presence Not Updating

   • The Presence model uses Laravel’s online method. Ensure your AppServiceProvider has:

     use Laravel\Presence\Presence;
     
     public function boot()
     {
         Presence::enableForModel(\App\Models\User::class);
     }
     

Debugging

1. Check Events Listen for events in Tinker to debug:

   \Aaix\FilamentChatBubbles\Events\MessageSent::dispatch($message);
   

   Use php artisan events:listen to see if events are fired.

2. Log Broadcasts Add logging to app/Providers/BroadcastServiceProvider.php:

   public function boot()
   {
       \Log::info('Broadcasting event:', ['event' => $event]);
   }
   

3. Clear Cache If bubbles or messages don’t appear, clear Filament and config caches:

   php artisan filament:cache:clear
   php artisan config:clear
   

Tips

1. Custom User Model Extend the HasPresence trait to your user model:

   use Aaix\FilamentChatBubbles\Traits\HasPresence;
   
   class User extends Authenticatable
   {
       use HasPresence;
   }
   

2. Message Read Receipts Use the markAsRead method to update message status:

   $message->markAsRead();
   

   Trigger this via a button click in the frontend.

3. Typing Indicators Implement a user-typing event to show typing indicators:

   \Aaix\FilamentChatBubbles\Facades\FilamentChatBubbles::userIsTyping($userId, true);
   

4. Dark Mode Support Override the bubble styles in your Filament theme:

   .filament-chat-bubbles-bubble {
       background: #333;
       color: #fff;
   }
   

5. Rate Limiting Add rate limiting to message endpoints in app/Http/Kernel.php:

   'throttle:api' => [
       \Aaix\FilamentChatBubbles\Http\Controllers\MessageController::class,
   ],
   

6. Localization Publish the language files and translate messages:

   php artisan vendor:publish --provider="Aaix\FilamentChatBubbles\FilamentChatBubblesServiceProvider" --tag="lang"