Fluxchat Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation

   composer require wirelabs/fluxchat
   php artisan fluxchat:install
   php artisan migrate
   

   Verify the fluxchat table exists in your database.

2. Basic Blade Integration Add the component to a view with required props:

   <livewire:fluxchat :contacts="$contacts" />
   

   Pass a collection of users (e.g., from a controller):

   $contacts = User::where('id', '!=', auth()->id())->limit(10)->get();
   

3. First Message

   • Open the chat UI in a browser.
   • Select a contact to start a conversation.
   • Type and send a message (polling mode works immediately).

4. Reverb Setup (Optional) If using Reverb:

   composer require beyondcode/reverb
   php artisan reverb:install
   

   Enable real-time in config/fluxchat.php:

   'realtime' => [
       'enabled' => true,
       'channel' => 'fluxchat',
   ],
   

Implementation Patterns

Core Workflows

1. Contact Management

   • Dynamic Loading: Fetch contacts via a Livewire property ($contacts).

     public $contacts;
     public function mount() {
         $this->contacts = User::active()->get();
     }
     

   • Search Filtering: Extend with a search input:

     <input wire:model.debounce.300ms="search" placeholder="Search...">
     

     public $search = '';
     public function getContactsProperty() {
         return User::where('name', 'like', "%{$this->search}%")
                     ->where('id', '!=', auth()->id())
                     ->get();
     }
     

2. Message Handling

   • Custom Logic: Override message creation in a Livewire component:

     use App\Models\Message;
     use Wirelabs\FluxChat\Livewire\Chat;
     
     class CustomChat extends Chat {
         protected function createMessage(array $data) {
             $message = Message::create([
                 'user_id' => auth()->id(),
                 'contact_id' => $data['contact_id'],
                 'content' => $data['content'],
                 'metadata' => $data['metadata'] ?? null,
             ]);
             return $message;
         }
     }
     

     Register the component in AppServiceProvider:

     Livewire::component('fluxchat', \App\Livewire\CustomChat::class);
     

3. Reverb Integration

   • Channel Setup: Create a Reverb channel for chat events:

     // app/Channels/FluxChatChannel.php
     namespace App\Channels;
     use BeyondCode\Reverb\Channel;
     
     class FluxChatChannel extends Channel {
         public function broadcastOn() {
             return 'fluxchat';
         }
     }
     

   • Event Dispatching: Trigger events in createMessage:

     broadcast(new \App\Events\MessageSent($message))->toOthers();
     

4. UI Customization

   • Flux UI Theming: Override Flux styles in your app’s CSS:

     .fluxchat-message {
         background: #f0f0f0;
     }
     

   • Component Slots: Extend the chat UI with slots:

     <livewire:fluxchat>
         <x-fluxchat::message.extra>
             <!-- Custom footer per message -->
         </x-fluxchat::message.extra>
     </livewire:fluxchat>
     

Integration Tips

1. Authentication

   • Ensure the chat component respects your auth system:

     public function mount() {
         $this->authId = auth()->id();
     }
     

   • Hide the chat if unauthenticated:

     @auth
         <livewire:fluxchat />
     @endauth
     

2. Database Schema

   • Extend the fluxchat_messages table for custom fields:

     Schema::table('fluxchat_messages', function (Blueprint $table) {
         $table->json('custom_data')->nullable();
     });
     

   • Update the Message model to cast the new field:

     protected $casts = [
         'custom_data' => 'array',
     ];
     

3. Testing

   • Unit Tests: Mock the Livewire component:

     $component = new (new \Wirelabs\FluxChat\Livewire\Chat)->resolveView();
     $this->assertViewHas('contacts', $component);
     

   • Feature Tests: Use Livewire’s testing helpers:

     $this->livewire(Chat::class, ['contacts' => $users])
          ->assertSee('Chat UI');
     

Gotchas and Tips

Pitfalls

1. Reverb Misconfiguration

   • Issue: Real-time messages fail silently if Reverb isn’t properly set up.
   • Fix: Verify:
     • Reverb is installed and running (php artisan reverb:start).
     • The fluxchat channel is subscribed in config/reverb.php.
     • The FluxChatChannel is registered in AppServiceProvider.

2. Polling vs. Realtime

   • Issue: Messages may appear out of order if polling and Reverb are both enabled.
   • Fix: Disable polling in config/fluxchat.php if using Reverb:

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

3. Contact Sync Delays

   • Issue: Contacts don’t update dynamically after creation/deletion.
   • Fix: Use Livewire’s updated() method to refresh contacts:

     public function updatedSearch {
         $this->dispatch('refresh-contacts');
     }
     

4. Flux UI Dependency

   • Issue: Missing Flux UI Pro components break the chat UI.
   • Fix: Ensure wirelabs/flux is installed and published:

     composer require wirelabs/flux
     php artisan vendor:publish --tag="flux"
     

Debugging

1. Livewire Logs

   • Enable Livewire logging in config/livewire.php:

     'log' => env('LIVEWIRE_LOG', true),
     

   • Check storage/logs/livewire.log for component lifecycle events.

2. Reverb Debugging

   • Tail Reverb logs:

     php artisan reverb:log
     

   • Verify WebSocket connections in browser dev tools (Network tab).

3. Database Queries

   • Use Laravel Debugbar to inspect SQL queries for the fluxchat table.

Extension Points

1. Custom Message Models

   • Override the default Message model by binding it in AppServiceProvider:

     FluxChat::setMessageModel(\App\Models\CustomMessage::class);
     

2. Event Hooks

   • Listen for FluxChat events (e.g., MessageSent):

     use Wirelabs\FluxChat\Events\MessageSent;
     
     MessageSent::listen(function ($message) {
         // Send notification, log, etc.
     });
     

3. API Endpoints

   • Expose chat data via API:

     Route::get('/api/chat/{contact}', function ($contact) {
         return FluxChat::getMessagesForContact($contact);
     });
     

4. Localization

   • Extend translations by publishing the lang file:

     php artisan vendor:publish --tag="fluxchat-lang"
     

   • Add custom translations in resources/lang/en/fluxchat.php:

     return [
         'custom_message' => 'Your custom message text',
     ];