Filament Chatify Integration Laravel Package

Getting Started

1. Install and confirm the dependency chain. Run composer require monzer/filament-chatify-integration and then inspect composer.json / composer.lock — this package is a thin bridge, so the version of munafio/chatify it pulls in (and whether it targets Livewire 2 or 3) determines everything else in your setup. Check this before building anything.

2. Let the underlying Chatify package bootstrap itself. The bridge typically doesn't re-publish Chatify's own assets. Run Chatify's installer (php artisan chatify:install, or vendor:publish --provider="Munafio\Chatify\ChatifyServiceProvider" manually), run php artisan migrate, and php artisan storage:link for avatars/attachments.

3. Configure broadcasting. Set BROADCAST_DRIVER=pusher, add PUSHER_APP_ID/KEY/SECRET/CLUSTER, and make sure the broadcast service provider is registered (Laravel 11+: php artisan install:broadcasting). Chatify is real-time-first — without Echo working you'll only see messages on refresh.

4. Register the plugin/page on your Filament panel. Open the package's service provider in vendor/monzer/filament-chatify-integration/src and see what it registers (a Plugin, a Page, or both). In most Filament v3 panels this is either ->plugin(ChatifyPlugin::make()) in your PanelProvider::panel() or a page class added to a discovery path. Confirm the exact method name in the README/source before wiring it in.

5. First use case: authenticate as two users in two browser sessions, open the chat page from the admin nav, send a message, and verify it arrives without a refresh. That one test validates install, guard, broadcasting, and asset publishing all at once.

Implementation Patterns

Guard alignment is the core architectural decision. Chatify authenticates and broadcasts against a guard/provider configured in config/chatify.php (user_model, and the guard used by its routes). Filament panels can use a different guard (admin, staff, etc.). Decide early: either point Chatify at your Filament guard/provider, or scope the chat page to a panel that shares the web guard. Nearly every "it 403s / messages send to the wrong user" bug traces back to this.

Register per-panel, not globally. If you have an admin panel and a customer panel, register the chat page/plugin explicitly on each PanelProvider where it belongs. This keeps the navigation clean and lets you control getNavigationGroup(), getNavigationLabel(), and shouldRegisterNavigation() on the page class.

Unread badge via the Chatify facade. Use Chatify's API (or the underlying ch_messages model) inside a small getNavigationBadge() on your page, or a custom Filament widget. Cache the count briefly (e.g. 10–30s) — computing it on every panel render for chatty users is a measurable cost.

Programmatic/system messaging. For "your export is ready" style notifications, don't drive the UI — use the Chatify facade or the message model directly to insert a message from a system user, then let broadcasting fan it out. Wrap this in a queued job so a slow broadcast doesn't block the action.

Notification bridge. Pair chat with Filament's database notifications: fire a notification on new chat message, link it back to the chat page. This gives you a unified inbox without duplicating Chatify's own UI.

Customize by publishing, not patching. Publish Chatify's views (vendor:publish --tag=chatify_views if supported, otherwise the provider's tags) and restyle to match your Filament theme — dark mode, panel primary color, spacing. Keep the original Blade in vendor/ untouched so upgrades are safe.

Extension point — subclass the page. If the bridge exposes a Filament Page class, extend it and override getViewData(), mount(), or the view constant rather than editing vendor files. Register your subclass in the panel instead.

Multi-tenant. If you use Filament tenancy, Chatify is not tenant-aware out of the box. Scope the user list and any custom message queries by tenant_id yourself, and be careful that Chatify's default "all users" contact list doesn't leak across tenants.

Gotchas and Tips

• Livewire version conflict is the #1 risk. Chatify historically pinned Livewire 2; Filament v3 requires Livewire 3. Before committing, run composer why munafio/chatify and check the resolved version supports Livewire 3. A silent composer resolution here can produce confusing "component not found" errors in the browser.

• Echo doesn't survive Filament's SPA navigation. With wire:navigate / Filament's client-side panel navigation, Chatify's window.Echo listeners are bound once on full page load and won't re-attach on navigation. Re-init or re-subscribe on livewire:navigated, or disable wire:navigate for the chat page. Symptom: messages arrive after a hard refresh but not after clicking around the panel.

• Broadcasting auth uses the wrong guard. /broadcasting/auth is protected by the default guard unless you configure Broadcast::routes(['middleware' => ['web', 'auth:admin']]). If private channels 403 while the page loads fine, this is it.

• Migration collisions and table names. Chatify ships its own migrations (messages/favorites, typically prefixed). If you've already got a messages table or you're adding this to an existing app, check for conflicts before migrate on production. Use php artisan migrate --pretend first.

• Asset publishing is separate and easy to forget. storage:link, config:clear, and re-publishing Chatify's JS/CSS after upgrades are classic "it's broken in production but fine locally" causes. After any deploy that touches the package: php artisan vendor:publish --force (with care), config:clear, view:clear, storage:link.

• Dark mode and CSS bleed. Chatify's stylesheet is scoped but not Filament-themed. Expect contrast issues in dark mode and sidebar padding mismatches. Fix in a published view or a small custom CSS file loaded via ->viteTheme() / FilamentAsset::register().

• Route prefix conflicts. Chatify registers routes under a configurable prefix (default chatify). If you have your own routes there, or you're behind a subdirectory, adjust config/chatify.php route.prefix and re-check with php artisan route:list --path=chatify.

• Debugging checklist: browser console for Pusher/Echo connection errors → php artisan route:list | grep chat → check storage/logs/laravel.log for auth/guard messages → verify config/chatify.php user_model matches your Filament auth model → confirm the panel's ->authGuard() matches Chatify's configured guard.

• File upload limits. Chatify respects PHP upload_max_filesize/post_max_size and its own config for max attachment size and disk. If users report silent upload failures, check both plus the storage disk's visibility setting — Laravel 11 defaults can leave private uploads inaccessible via the public URL Chatify generates.

• Testing. Use actingAs($user, 'admin') with the correct guard in feature tests, Event::fake() / Broadcast::fake() for send-message flows, and Notification::fake() if you bridge to Filament notifications. Add one integration test that hits the chat page and asserts a 200 for the intended guard — that test alone catches most breakage from future Filament/Chatify upgrades.