Filament Inbox Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require qalainau/filament-inbox
   

   Publish the package assets and migrations:

   php artisan vendor:publish --provider="Qalainau\FilamentInbox\FilamentInboxServiceProvider" --tag="filament-inbox-migrations"
   php artisan vendor:publish --provider="Qalainau\FilamentInbox\FilamentInboxServiceProvider" --tag="filament-inbox-config"
   php artisan vendor:publish --provider="Qalainau\FilamentInbox\FilamentInboxServiceProvider" --tag="filament-inbox-assets"
   

   Run migrations:

   php artisan migrate
   

2. Register the Plugin Add to your app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Qalainau\FilamentInbox\FilamentInboxPlugin::make(),
           ]);
   }
   

3. First Use Case

   • Log in as a user with the filament-inbox permission.
   • Navigate to the Inbox tab to view messages.
   • Compose a message using the Compose button to send your first internal message.

Implementation Patterns

Core Workflows

1. Message Composition

   • Use the Compose button to create a new message.
   • Supports rich text formatting (via Filament’s editor) and file attachments.
   • Recipients are auto-suggested from your user database (configurable via recipient_resolver).

2. Thread Management

   • Reply to messages to create threaded conversations.
   • Use Reply All for group replies.
   • Forward messages with original headers preserved.

3. Message Organization

   • Star important messages for quick access via the Starred tab.
   • Trash messages to move them to the Trash tab (configurable retention via trash_retention_days).
   • Bulk actions: Select multiple messages to mark as read or move to trash.

4. Read Receipts

   • Enable per-recipient read tracking via read_receipts_enabled in config.
   • Status indicators (e.g., "Read", "Unread") appear in the UI.

5. Multi-Tenancy

   • Supports tenant isolation via tenant_resolver in config.
   • Messages are scoped to the current tenant by default.

Integration Tips

1. Customizing Recipients Override the default recipient resolver in config/filament-inbox.php:

   'recipient_resolver' => \App\Services\CustomRecipientResolver::class,
   

   Implement Qalainau\FilamentInbox\Contracts\RecipientResolver.

2. Extending Message Data Add custom fields to messages by publishing the migration and extending the Message model:

   use Qalainau\FilamentInbox\Database\Models\Message;
   
   class ExtendedMessage extends Message
   {
       protected $casts = [
           'custom_field' => 'string',
       ];
   }
   

3. Customizing the UI Override blade templates by publishing views:

   php artisan vendor:publish --provider="Qalainau\FilamentInbox\FilamentInboxServiceProvider" --tag="filament-inbox-views"
   

   Modify files in resources/views/vendor/filament-inbox/.

4. Adding Permissions Use Filament’s gate system to restrict access:

   Gate::define('filament-inbox-access', function ($user) {
       return $user->hasRole(['admin', 'support']);
   });
   

5. Event Listeners Listen to message events (e.g., MessageSent, MessageRead) for custom logic:

   use Qalainau\FilamentInbox\Events\MessageSent;
   
   MessageSent::listen(function (MessageSent $event) {
       // Log or notify when a message is sent
   });
   

6. Search and Filters Extend the default search/filter logic by overriding the InboxResource:

   use Qalainau\FilamentInbox\Resources\InboxResource;
   
   class CustomInboxResource extends InboxResource
   {
       public static function getRelations(): array
       {
           return array_merge(parent::getRelations(), [
               // Add custom relations
           ]);
       }
   }
   

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • If you extend the Message model, ensure your migration doesn’t conflict with the package’s default schema.
   • Fix: Use Schema::table() instead of Schema::create() for custom fields.

2. Permission Issues

   • Users without the filament-inbox permission will see a 403 error.
   • Fix: Verify permissions in config/filament.php under permissions.

3. Attachment Limits

   • Large attachments may cause performance issues or exceed server limits.
   • Fix: Configure max_attachment_size in config/filament-inbox.php (default: 10MB).

4. Threading Quirks

   • Replying to a forwarded message may create unexpected threads.
   • Fix: Use reply_to_message_id explicitly when forwarding to maintain thread context.

5. Read Receipts Overhead

   • Enabling read receipts adds database queries for each recipient.
   • Fix: Disable for high-traffic systems or use caching for receipt status.

Debugging

1. Log Messages Enable debug mode in config/filament-inbox.php:

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

   Logs will appear in storage/logs/filament-inbox.log.

2. Database Issues

   • Check if the filament_inbox_messages table exists and has the correct schema.
   • Fix: Re-run migrations or inspect the published migration file.

3. Asset Loading

   • If CSS/JS fails to load, verify the published assets are linked in resources/views/vendor/filament-inbox/partials/script.blade.php.

Extension Points

1. Custom Message Types Extend the Message model to support different message types (e.g., "Notification", "Support Ticket"):

   class Message extends \Qalainau\FilamentInbox\Database\Models\Message
   {
       protected $casts = [
           'type' => 'string',
       ];
   }
   

   Filter messages in the UI by type using custom resources.

2. Webhook Integration Trigger external actions (e.g., Slack notifications) via event listeners:

   MessageSent::listen(function ($event) {
       // Send Slack notification
   });
   

3. API Endpoints Expose message data via Laravel API routes:

   Route::get('/api/messages', [\Qalainau\FilamentInbox\Http\Controllers\MessageController::class, 'index']);
   

4. Custom Actions Add buttons or actions to the message list/table:

   use Filament\Tables\Actions\Action;
   
   Action::make('customAction')
       ->action(function (Message $record) {
           // Custom logic
       });
   

5. Multi-Language Support Override translation strings in resources/lang/vendor/filament-inbox. Example:

   {
       "messages": {
           "compose": "Send a New Message"
       }
   }