Filament Team Chat Laravel Package

Getting Started

Minimal Steps to First Chat

1. Install and Publish:

   composer require qalainau/filament-team-chat
   php artisan vendor:publish --tag=team-chat-migrations
   php artisan migrate
   

2. Register Plugin: Add to your panel() method in AppServiceProvider or panel config:

   ->plugin(FilamentTeamChatPlugin::make())
   

3. Enable User Support: Add the trait to your User model:

   use Filament\TeamChat\Concerns\HasTeamChat;
   

4. Tailwind Setup (if not already configured):

   php artisan filament:theme
   

   Add to resources/css/filament/admin/theme.css:

   @source '../../../../vendor/qalainau/filament-team-chat/resources/views/**/*';
   

   Run npm run build.

5. First Use Case: Visit /admin/team-chat and start a DM with @user or create a public channel (e.g., #general). Test sending a message with Markdown (e.g., **bold** text) and an attachment.

Implementation Patterns

Daily Developer Workflows

1. Channel/DM Management

• Programmatic Creation:

  // Create a public channel
  $channel = Channel::create([
      'name' => 'dev-discussion',
      'slug' => 'dev-discussion',
      'type' => 'public',
      'created_by' => auth()->id(),
  ]);
  $channel->members()->attach(auth()->id(), ['role' => 'owner']);
  
  // Create a DM
  $dm = auth()->user()->findOrCreateDirectMessage($otherUser);
  

• Bulk Operations: Use Channel::query()->where(...) or Conversation::query()->where(...) with Laravel’s query builder for filtering (e.g., archived channels, active DMs).

2. Message Handling

• Sending Messages:

  $message = app(SendMessage::class)->execute(
      messageable: $channel, // Channel or Conversation
      userId: auth()->id(),
      body: 'Hello @Jordan! Check this `code`.',
      files: [new UploadedFile(...)] // Optional
  );
  

• Thread Replies: Pass parentId to nest replies:

  app(SendMessage::class)->execute(
      messageable: $channel,
      userId: auth()->id(),
      body: 'Reply to parent',
      parentId: $parentMessage->id
  );
  

3. Reactions and Mentions

• Toggle Reactions:

  app(ToggleReaction::class)->execute($message->id, auth()->id(), '👍');
  

• Trigger Mentions: Use @user, @channel, or @here in messages. Parse mentions programmatically:

  $mentions = $message->mentions()->where('type', 'user')->get();
  

4. Search and Notifications

• Search Messages:

  $results = app(SearchMessages::class)->execute(
      userId: auth()->id(),
      query: 'deploy',
      limit: 20
  );
  

• Mark as Read:

  app(MarkAsRead::class)->execute($channel, auth()->id());
  

5. Multi-Tenancy

• Enable in config/team-chat.php:

  'tenancy' => [
      'enabled' => true,
      'model' => \App\Models\Team::class,
      'resolver' => fn() => Filament::getTenant()->id,
  ],
  

• Scope queries automatically:

  $channel = Channel::where('team_id', $teamId)->first();
  

6. Customizing UI

• Override Livewire components by copying from vendor/qalainau/filament-team-chat/resources/views to resources/views/vendor/filament/team-chat.
• Extend Tailwind classes in your theme file (e.g., resources/css/filament/admin/theme.css).

7. Testing

• Use the package’s test suite as a reference:

  // Example: Test DM creation
  public function test_dm_creation()
  {
      $user1 = User::factory()->create();
      $user2 = User::factory()->create();
      $dm = $user1->findOrCreateDirectMessage($user2);
      $this->assertInstanceOf(Conversation::class, $dm);
  }
  

8. Integrations

• Webhooks: Listen for team-chat.message.sent events (dispatches in SendMessage action).
• Notifications: Extend Filament\TeamChat\Notifications\MessageNotification for custom alerts.
• API Endpoints: Build custom routes to fetch messages or channels for non-Filament clients.

Gotchas and Tips

Pitfalls and Debugging

1. Polling Delays:

   • Issue: Messages or sidebar updates feel slow due to Livewire polling (configurable in config/team-chat.php).
   • Fix: Reduce polling intervals (e.g., 'messages' => 2) for critical paths, but monitor server load. For high-traffic apps, consider adding WebSocket support via laravel-websockets.

2. Tailwind Conflicts:

   • Issue: Custom styles override package styles if Tailwind classes collide.
   • Fix: Scope package classes with !important in your theme or use arbitrary variants:

     .team-chat-custom { @apply !important; }
     

3. File Uploads:

   • Issue: Large files or high upload volumes may fill storage.
   • Fix: Configure uploads.max_size (default: 10MB) and set up disk cleanup (e.g., tc_attachments table pruning).

4. Multi-Tenancy Quirks:

   • Issue: Tenant resolution fails if Filament::getTenant() returns null.
   • Fix: Provide a fallback resolver:

     'resolver' => fn() => auth()->user()->team_id ?? null,
     

5. Mentions Parsing:

   • Issue: @user mentions don’t resolve if the user’s name or email changes.
   • Fix: Use user()->name consistently and update mentions via a queue job after user updates.

6. Livewire State Persistence:

   • Issue: Thread panels or modals close unexpectedly.
   • Fix: Ensure wire:key is unique in Livewire components (e.g., wire:key="thread-{{ $message->id }}").

7. Database Locking:

   • Issue: Concurrent writes to tc_messages or tc_read_receipts cause deadlocks.
   • Fix: Add indexes to foreign keys and use transactions sparingly:

     DB::transaction(function () use ($message) {
         $message->reactions()->create([...]);
     });
     

Configuration Quirks

1. Table Prefix:

   • Tip: Change tc_ to a custom prefix (e.g., app_tc_) if your database already uses tc_ for other tables.

2. User Model:

   • Tip: If using a custom user model, ensure it implements Filament\TeamChat\Contracts\User:

     use Filament\TeamChat\Contracts\User as TeamChatUser;
     class User implements TeamChatUser { ... }
     

3. Dark Mode:

   • Tip: Force dark mode for all users by overriding the package’s CSS:

     .dark .team-chat-dark { @apply bg-gray-800; }
     

4. Notifications Table:

   • Tip: If you skip php artisan make:notifications-table, @mentions and DM alerts will be silently ignored. Add it later with:

     php artisan make:notifications-table --force
     

Extension Points

1. Custom Reactions:

   • Extend the reactions table and override the ToggleReaction action to support custom emojis (e.g., :rocket:).

2. Message Validation:

   • Override Filament\TeamChat\Actions\SendMessage to add custom rules (e.g., block profanity):

     public function rules(): array
     {
         return array_merge(parent::rules(), [
             'body' => ['required', 'max:2000', 'profanity'], // Custom rule
         ]);
     }
     

3. Channel Types:

   • Add a type column to tc_channels (e.g., announcement, private) and filter in the sidebar:

     Channel::query()->where('type', 'announcement')->get();
     

4. Message Events:

   • Dispatch custom events in SendMessage:

     event(new MessageSent($message));