Getting Started

Minimal Setup

Installation

composer require hamoi1/filachat

Publish the config and migrations:

php artisan vendor:publish --provider="Hamoi1\FilaChat\FilaChatServiceProvider" --tag="filachat-config"
php artisan migrate

Configure Roles Edit config/filachat.php to define agent and user roles (or disable role restrictions entirely):
```
'roles' => [
    'agent' => ['admin', 'support'],
    'user' => ['customer'],
],
```

First Use Case Register the plugin in your Filament panel:

// app/Providers/Filament/AdminPanelProvider.php
public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            \Hamoi1\FilaChat\Plugin::make(),
        ]);
}

Access the chat via the Filament sidebar (default location: chat route).

Implementation Patterns

Core Workflows

Role-Based Chat Initialization Dynamically enable/disable chat UI based on user roles:

// In a Filament resource or page
use Hamoi1\FilaChat\Facades\FilaChat;

if (FilaChat::isAgent($user)) {
    // Show agent-specific UI
} elseif (FilaChat::isUser($user)) {
    // Show user-specific UI
}

Real-Time Integration
- Broadcast Mode (Recommended): Ensure your Laravel queue worker (laravel-worker) is running and configure BROADCAST_DRIVER in .env (e.g., pusher or redis). Publish events via:
```
event(new \Hamoi1\FilaChat\Events\MessageSent($message));
```
- Polling Fallback: Configure polling interval in config/filachat.php:
```
'polling' => [
    'interval' => 5, // seconds
],
```

Attachment Handling Customize file rules in the config:

'attachments' => [
    'max_size' => 10 * 1024 * 1024, // 10MB
    'allowed_types' => ['image/jpeg', 'image/png', 'application/pdf'],
],

Access attachments in a message:

$message->attachments()->each(function ($attachment) {
    // Preview: $attachment->getUrl()
    // Metadata: $attachment->mime_type, $attachment->size
});

Conversation Management

Create a Conversation:

$conversation = \Hamoi1\FilaChat\Models\Conversation::create([
    'user_id' => auth()->id(),
    'agent_id' => $agent->id,
    'subject' => 'Support Request',
]);

Mark as Completed:
```
$conversation->complete();
```

Permanent Deletion:

php artisan filachat:cleanup:conversations --days=30

Integration Tips

Customize Sidebar Placement: Override the default sidebar position via config or plugin fluent API:
```
\Hamoi1\FilaChat\Plugin::make()
    ->sidebarPosition('before:resources')
```

Extend Message Model: Add custom fields to the messages table by publishing and modifying the migration:

php artisan vendor:publish --tag="filachat-migrations"

Then extend the model:

use Hamoi1\FilaChat\Models\Message;

class CustomMessage extends Message
{
    protected $casts = [
        ...,
        'custom_field' => 'string',
    ];
}

Gotchas and Tips

Pitfalls

Broadcast Driver Misconfiguration
- Issue: Real-time updates fail silently if the broadcast driver is misconfigured.
- Fix: Verify .env settings and queue worker status:
```
php artisan queue:work --daemon
```
- Debug: Check Laravel logs for BroadcastServiceProvider errors.
Role Conflicts
- Issue: Users may see unexpected chat UI if roles aren’t properly defined.
- Fix: Validate roles in config/filachat.php and test with:
```
php artisan filachat:test-roles
```
Attachment Storage
- Issue: Uploads may fail if the storage symlink isn’t set or disk isn’t configured.
- Fix: Ensure FILESYSTEM_DISK in .env points to a writable disk (e.g., public).
Sidebar Visibility
- Issue: Chat sidebar may not appear if the plugin isn’t registered correctly.
- Fix: Verify the plugin is added to the panel after Filament\PanelPluginList:
```
->plugins([
    \Hamoi1\FilaChat\Plugin::make(),
])
```

Debugging

Log Events: Enable debug mode in config/filachat.php:
```
'debug' => env('FILACHAT_DEBUG', false),
```
Check logs for event broadcasting or polling activity.
Test Polling: Simulate polling delays by adjusting the interval and monitoring:
```
'polling' => [
    'interval' => 1, // For testing
],
```

Extension Points

Customize UI Override Blade views by publishing them:

php artisan vendor:publish --tag="filachat-views"

Extend the chat page:

// app/Filament/Resources/ChatPage.php
namespace App\Filament\Resources;

use Hamoi1\FilaChat\Resources\ChatPage as BaseChatPage;

class ChatPage extends BaseChatPage
{
    protected static string $view = 'filachat::pages.chat.custom';
}

Add Custom Fields Extend the Conversation or Message models:

// app/Models/CustomConversation.php
use Hamoi1\FilaChat\Models\Conversation;

class CustomConversation extends Conversation
{
    protected $casts = [
        'priority' => 'integer',
    ];
}

Update the migration and config to include the new field.

Override Default Behavior Bind custom logic to events:

// In a service provider
\Hamoi1\FilaChat\Events\MessageSent::class => function ($event) {
    // Add custom logic (e.g., notifications)
},

Maintenance Commands Schedule cleanup tasks in app/Console/Kernel.php:

protected function schedule(Schedule $schedule): void
{
    $schedule->command('filachat:cleanup:conversations --days=30')
            ->dailyAt('2:00');
}

Configuration Quirks

Polling vs. Broadcast:
- Polling is not a drop-in replacement for broadcast. Test both modes in staging.
- Broadcast requires additional setup (Pusher/Redis), while polling is simpler but less responsive.
Attachment Cleanup: The filachat:cleanup:attachments command only runs during conversation cleanup. Manually trigger it if needed:
```
php artisan filachat:cleanup:attachments
```
Role Restrictions: Disabling role restrictions ('roles' => []) allows all users to chat, but removes agent/user-specific features (e.g., send locks). Use cautiously.

Filachat Laravel Package