Filament 实时广播通知完整指南基于 Laravel Echo 与 WebSocket 的实时推送实践【免费下载链接】filamentA powerful open-source UI framework for Laravel • Build and ship apps admin panels fast with Livewire项目地址: https://gitcode.com/GitHub_Trending/fi/filamentFilament 默认通过 Laravel Session 以闪存消息的方式在下一次页面加载时展示通知。本指南讲解如何在 Filament 中开启实时广播通知Broadcast Notifications通过原生集成的 Laravel Echo 与 Pusher 兼容的 WebSocket 服务端将通知在生成的同时推送到已登录用户正在浏览的页面上——典型的应用场景包括队列任务处理完成后向用户实时弹出成功提示。读完本文你将掌握三种发送广播通知的 API 写法、Panel Builder 中完整的 WebSocket 接线步骤以及其底层实现原理。引言从 Session 闪存到实时广播在 Filament 中默认的通知机制如Notification::make()-send()会把通知写入 Session随后由 Livewire 通知组件 在下一次请求时从session()-pull(filament.notifications)取出并渲染见 Notification.php 的send()方法。这种机制简单可靠但存在天然局限通知只能在下一次 HTTP 请求发生时展示。如果用户停留在页面上等待某个后台任务例如导入、导出、异步生成报告完成他不会收到任何即时反馈。广播通知正是为此而生它借助 Laravel 的广播系统Broadcasting与 Laravel Echo 客户端将通知通过 WebSocket 实时推送到用户的浏览器一个典型场景在队列任务Queued Job处理完毕后向其发起者发送一条处理成功的临时通知——即使用户没有发起任何新的请求通知也会实时弹出Filament 提供了对Laravel Echo的原生集成。使用前需要确保Echo 已在项目中安装同时配置好一个服务端 WebSocket 集成如 Pusher 或任何 Pusher 协议兼容的服务端。发送广播通知的三种方式根据使用场景的差异Filament 提供了三种发送广播通知的途径你可以选择最顺手的一种。方式一流式 API——broadcast($recipient)use Filament\Notifications\Notification; $recipient auth()-user(); Notification::make() -title(Saved successfully) -broadcast($recipient);从源码看broadcast()方法 的签名接受Model | Authenticatable | Collection | array也就是说你既可以传单个用户也可以传入一个用户集合或数组——方法内部会将其归一化为数组并逐个调用$user-notify($this-toBroadcast())最终走 Laravel 标准的通知广播通道。方式二通过模型的notify()方法use Filament\Notifications\Notification; $recipient auth()-user(); $recipient-notify( Notification::make() -title(Saved successfully) -toBroadcast(), )这里的关键是toBroadcast()该方法 会先把通知序列化为数组、附加format字段值为filament用于标识这是 Filament 格式的通知然后构造一个BroadcastNotification实例返回。方式三传统 Laravel 通知类如果你习惯使用标准的 Laravel 通知类例如在队列任务中直接调用$user-notify(...)可以在通知类的toBroadcast()方法中返回 Filament 构造好的广播消息use App\Models\User; use Filament\Notifications\Notification; use Illuminate\Notifications\Messages\BroadcastMessage; public function toBroadcast(User $notifiable): BroadcastMessage { return Notification::make() -title(Saved successfully) -getBroadcastMessage(); }getBroadcastMessage()方法 与toBroadcast()的序列化逻辑一致将通知转数组后附加format filament并包装为 Laravel 标准的BroadcastMessage返回。底层原理BroadcastNotification 与消息数据格式三种写法最终都汇聚到 BroadcastNotification这个类有四个值得注意的实现细节实现了ShouldQueue并混入Queueable广播通知会进入队列异步投递不会阻塞你的请求via()固定返回[broadcast]只走广播通道不落库toBroadcast()返回BroadcastMessage并透传你为通知设置的connection与queue来自Queueabletrait因此可以精细控制消息投递到哪个队列连接消息负载即Notification::toArray()的输出包含id、title、body、icon、iconColor、color、status、duration、actions、view等字段见 Notification.php 的toArray()再附加format字段。以上行为均有测试背书参见 BroadcastNotificationTest.php它验证了构造数据被正确存储、via()返回[broadcast]、toBroadcast()返回BroadcastMessage实例以及类实现了ShouldQueue。在 Panel 中配置 WebSocket 环境Panel Builder 内置了对实时广播通知与数据库通知的底层支持但要真正跑通还需要完成一系列安装与配置。官方步骤共六步阅读 Laravel 广播文档先熟悉 Laravel 的 Broadcasting 机制频道、事件、鉴权等概念。配置服务端 WebSocket安装并配置一个 Pusher 兼容的服务端集成如 PusherLaravel 的BROADCAST_CONNECTION等环境变量按广播文档设置。发布 Filament 包配置如果尚未发布php artisan vendor:publish --tagfilament-config编辑config/filament.php取消broadcasting.echo配置段的注释并根据你的广播安装情况正确填写各项设置。确保.env中存在对应的VITE_*环境变量Echo 客户端初始化所需。清除相关缓存让新配置生效php artisan route:clear php artisan config:clear完成以上步骤后你的 Panel 就会开始连接广播服务。例如登录 Pusher 的调试控制台Debug Console每次加载页面时都应该能看到一个来自浏览器的入站连接。config/filament.php中的 Echo 配置详解第 4 步对应的配置段位于 config/filament.php默认以注释形式给出取消注释后形如broadcasting [ echo [ broadcaster pusher, key env(VITE_PUSHER_APP_KEY), cluster env(VITE_PUSHER_APP_CLUSTER), wsHost env(VITE_PUSHER_HOST), wsPort env(VITE_PUSHER_PORT), wssPort env(VITE_PUSHER_PORT), authEndpoint /broadcasting/auth, disableStats true, encrypted true, forceTLS env(VITE_PUSHER_SCHEME, https) https, ], ],各参数的作用从配置注释与 Echo 客户端行为推断参数说明典型值broadcaster广播驱动名称Pusher 协议兼容服务端均可使用pusherkeyPusher 应用的 Key对应前端VITE_PUSHER_APP_KEYenv(VITE_PUSHER_APP_KEY)clusterPusher 集群标识对应VITE_PUSHER_APP_CLUSTERenv(VITE_PUSHER_APP_CLUSTER)wsHostWebSocket 主机地址自建服务时必填env(VITE_PUSHER_HOST)wsPortWebSocket 端口明文连接env(VITE_PUSHER_PORT)wssPortWebSocket 安全端口TLS 连接env(VITE_PUSHER_PORT)authEndpoint私有频道鉴权端点Laravel 默认路由/broadcasting/authdisableStats是否禁用统计上报trueencrypted是否启用加密连接trueforceTLS是否强制 TLS依据VITE_PUSHER_SCHEME是否为httpsenv(VITE_PUSHER_SCHEME, https) https客户端 Echo 是如何被引入的很多开发者会疑惑我没有手动加载 Echo为什么 Panel 就能监听频道。答案在 FilamentServiceProvider.phpPanel 包将../dist/echo.js注册为核心资源Js::make(echo, ...)-core()并随 Panel 前端资产一并加载。打开 dist/echo.js 可以看到它实际上是Pusher JavaScript 库v7.6.0与 Echo 工厂window.EchoFactory的打包产物并默认注册了broadcaster: pusher、authEndpoint: /broadcasting/auth等默认选项同时支持reverb、socket.io、null等驱动。而 notifications.blade.php 中的script块则负责接线先检查window.Echo是否已就绪就绪后通过window.Echo.private(...)订阅当前用户的私有频道并调用.notification(...)监听 Laravel 广播通知事件收到通知后延迟 500ms 调用$wire.handleBroadcastNotification(notification)把负载交给 Livewire 组件渲染为页面上真实的通知。广播频道如何命名与自定义订阅的是哪个私有频道这取决于 Notifications.php 的getBroadcastChannel()方法如果当前用户模型定义了receivesBroadcastNotificationsOn()方法则直接使用其返回值作为频道名——这是官方预留的自定义入口否则默认频道名为模型类名反斜杠替换为点. 主键例如App.Models.User.1。与之对称服务端 DatabaseNotificationsSent 事件 在broadcastOn()中采用了完全相同的命名逻辑来创建PrivateChannel并用broadcastAs()将事件名定义为database-notifications.sent。这一点与 database-notifications.blade.php 中的监听逻辑相呼应数据库通知弹层订阅该事件后会延迟 500ms 触发$wire.call($refresh)重新拉取最新通知列表从而实现新数据库通知到达后铃铛角标实时刷新。客户端如何安全地还原通知当广播负载到达浏览器时handleBroadcastNotification()会先校验format filament只有 Filament 格式的通知才会被接受随后通过Notification::fromArray()还原为完整通知对象并入队展示。这一校验避免了无关广播事件被误当作 Filament 通知渲染。验证与常见排查点完成配置后可按以下思路验证与排查连接验证打开 Pusher或所用服务端的调试控制台刷新任一 Panel 页面应观察到来自浏览器的入站 WebSocket 连接若没有优先确认 Echo 配置段是否已取消注释、VITE_*变量是否齐备。缓存问题修改config/filament.php或.env后务必执行php artisan route:clear与php artisan config:clear否则新配置不会生效。频道鉴权广播走的是PrivateChannel需要确保 Laravel 广播路由/broadcasting/auth可用且当前用户有权限订阅自己的频道。队列消费由于BroadcastNotification实现了ShouldQueue请确认队列 worker 正在运行否则通知不会真正投递。测试先行如需为广播逻辑编写自动化测试可参照 BroadcastNotificationTest.php 验证通知的序列化、通道与队列行为。相关文件索引文档主体03-broadcast-notifications.md通知核心类Notification.phpbroadcast()、toBroadcast()、getBroadcastMessage()广播通知适配类BroadcastNotification.php前端接收组件Livewire/Notifications.php 与 notifications.blade.php数据库通知刷新事件DatabaseNotificationsSent.phpEcho 客户端配置config/filament.php打包的 Echo/Pusher 客户端dist/echo.js 及其注册处 FilamentServiceProvider.php单元测试BroadcastNotificationTest.php【免费下载链接】filamentA powerful open-source UI framework for Laravel • Build and ship apps admin panels fast with Livewire项目地址: https://gitcode.com/GitHub_Trending/fi/filament创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Filament 实时广播通知完整指南：基于 Laravel Echo 与 WebSocket 的实时推送实践
Filament 实时广播通知完整指南基于 Laravel Echo 与 WebSocket 的实时推送实践【免费下载链接】filamentA powerful open-source UI framework for Laravel • Build and ship apps admin panels fast with Livewire项目地址: https://gitcode.com/GitHub_Trending/fi/filamentFilament 默认通过 Laravel Session 以闪存消息的方式在下一次页面加载时展示通知。本指南讲解如何在 Filament 中开启实时广播通知Broadcast Notifications通过原生集成的 Laravel Echo 与 Pusher 兼容的 WebSocket 服务端将通知在生成的同时推送到已登录用户正在浏览的页面上——典型的应用场景包括队列任务处理完成后向用户实时弹出成功提示。读完本文你将掌握三种发送广播通知的 API 写法、Panel Builder 中完整的 WebSocket 接线步骤以及其底层实现原理。引言从 Session 闪存到实时广播在 Filament 中默认的通知机制如Notification::make()-send()会把通知写入 Session随后由 Livewire 通知组件 在下一次请求时从session()-pull(filament.notifications)取出并渲染见 Notification.php 的send()方法。这种机制简单可靠但存在天然局限通知只能在下一次 HTTP 请求发生时展示。如果用户停留在页面上等待某个后台任务例如导入、导出、异步生成报告完成他不会收到任何即时反馈。广播通知正是为此而生它借助 Laravel 的广播系统Broadcasting与 Laravel Echo 客户端将通知通过 WebSocket 实时推送到用户的浏览器一个典型场景在队列任务Queued Job处理完毕后向其发起者发送一条处理成功的临时通知——即使用户没有发起任何新的请求通知也会实时弹出Filament 提供了对Laravel Echo的原生集成。使用前需要确保Echo 已在项目中安装同时配置好一个服务端 WebSocket 集成如 Pusher 或任何 Pusher 协议兼容的服务端。发送广播通知的三种方式根据使用场景的差异Filament 提供了三种发送广播通知的途径你可以选择最顺手的一种。方式一流式 API——broadcast($recipient)use Filament\Notifications\Notification; $recipient auth()-user(); Notification::make() -title(Saved successfully) -broadcast($recipient);从源码看broadcast()方法 的签名接受Model | Authenticatable | Collection | array也就是说你既可以传单个用户也可以传入一个用户集合或数组——方法内部会将其归一化为数组并逐个调用$user-notify($this-toBroadcast())最终走 Laravel 标准的通知广播通道。方式二通过模型的notify()方法use Filament\Notifications\Notification; $recipient auth()-user(); $recipient-notify( Notification::make() -title(Saved successfully) -toBroadcast(), )这里的关键是toBroadcast()该方法 会先把通知序列化为数组、附加format字段值为filament用于标识这是 Filament 格式的通知然后构造一个BroadcastNotification实例返回。方式三传统 Laravel 通知类如果你习惯使用标准的 Laravel 通知类例如在队列任务中直接调用$user-notify(...)可以在通知类的toBroadcast()方法中返回 Filament 构造好的广播消息use App\Models\User; use Filament\Notifications\Notification; use Illuminate\Notifications\Messages\BroadcastMessage; public function toBroadcast(User $notifiable): BroadcastMessage { return Notification::make() -title(Saved successfully) -getBroadcastMessage(); }getBroadcastMessage()方法 与toBroadcast()的序列化逻辑一致将通知转数组后附加format filament并包装为 Laravel 标准的BroadcastMessage返回。底层原理BroadcastNotification 与消息数据格式三种写法最终都汇聚到 BroadcastNotification这个类有四个值得注意的实现细节实现了ShouldQueue并混入Queueable广播通知会进入队列异步投递不会阻塞你的请求via()固定返回[broadcast]只走广播通道不落库toBroadcast()返回BroadcastMessage并透传你为通知设置的connection与queue来自Queueabletrait因此可以精细控制消息投递到哪个队列连接消息负载即Notification::toArray()的输出包含id、title、body、icon、iconColor、color、status、duration、actions、view等字段见 Notification.php 的toArray()再附加format字段。以上行为均有测试背书参见 BroadcastNotificationTest.php它验证了构造数据被正确存储、via()返回[broadcast]、toBroadcast()返回BroadcastMessage实例以及类实现了ShouldQueue。在 Panel 中配置 WebSocket 环境Panel Builder 内置了对实时广播通知与数据库通知的底层支持但要真正跑通还需要完成一系列安装与配置。官方步骤共六步阅读 Laravel 广播文档先熟悉 Laravel 的 Broadcasting 机制频道、事件、鉴权等概念。配置服务端 WebSocket安装并配置一个 Pusher 兼容的服务端集成如 PusherLaravel 的BROADCAST_CONNECTION等环境变量按广播文档设置。发布 Filament 包配置如果尚未发布php artisan vendor:publish --tagfilament-config编辑config/filament.php取消broadcasting.echo配置段的注释并根据你的广播安装情况正确填写各项设置。确保.env中存在对应的VITE_*环境变量Echo 客户端初始化所需。清除相关缓存让新配置生效php artisan route:clear php artisan config:clear完成以上步骤后你的 Panel 就会开始连接广播服务。例如登录 Pusher 的调试控制台Debug Console每次加载页面时都应该能看到一个来自浏览器的入站连接。config/filament.php中的 Echo 配置详解第 4 步对应的配置段位于 config/filament.php默认以注释形式给出取消注释后形如broadcasting [ echo [ broadcaster pusher, key env(VITE_PUSHER_APP_KEY), cluster env(VITE_PUSHER_APP_CLUSTER), wsHost env(VITE_PUSHER_HOST), wsPort env(VITE_PUSHER_PORT), wssPort env(VITE_PUSHER_PORT), authEndpoint /broadcasting/auth, disableStats true, encrypted true, forceTLS env(VITE_PUSHER_SCHEME, https) https, ], ],各参数的作用从配置注释与 Echo 客户端行为推断参数说明典型值broadcaster广播驱动名称Pusher 协议兼容服务端均可使用pusherkeyPusher 应用的 Key对应前端VITE_PUSHER_APP_KEYenv(VITE_PUSHER_APP_KEY)clusterPusher 集群标识对应VITE_PUSHER_APP_CLUSTERenv(VITE_PUSHER_APP_CLUSTER)wsHostWebSocket 主机地址自建服务时必填env(VITE_PUSHER_HOST)wsPortWebSocket 端口明文连接env(VITE_PUSHER_PORT)wssPortWebSocket 安全端口TLS 连接env(VITE_PUSHER_PORT)authEndpoint私有频道鉴权端点Laravel 默认路由/broadcasting/authdisableStats是否禁用统计上报trueencrypted是否启用加密连接trueforceTLS是否强制 TLS依据VITE_PUSHER_SCHEME是否为httpsenv(VITE_PUSHER_SCHEME, https) https客户端 Echo 是如何被引入的很多开发者会疑惑我没有手动加载 Echo为什么 Panel 就能监听频道。答案在 FilamentServiceProvider.phpPanel 包将../dist/echo.js注册为核心资源Js::make(echo, ...)-core()并随 Panel 前端资产一并加载。打开 dist/echo.js 可以看到它实际上是Pusher JavaScript 库v7.6.0与 Echo 工厂window.EchoFactory的打包产物并默认注册了broadcaster: pusher、authEndpoint: /broadcasting/auth等默认选项同时支持reverb、socket.io、null等驱动。而 notifications.blade.php 中的script块则负责接线先检查window.Echo是否已就绪就绪后通过window.Echo.private(...)订阅当前用户的私有频道并调用.notification(...)监听 Laravel 广播通知事件收到通知后延迟 500ms 调用$wire.handleBroadcastNotification(notification)把负载交给 Livewire 组件渲染为页面上真实的通知。广播频道如何命名与自定义订阅的是哪个私有频道这取决于 Notifications.php 的getBroadcastChannel()方法如果当前用户模型定义了receivesBroadcastNotificationsOn()方法则直接使用其返回值作为频道名——这是官方预留的自定义入口否则默认频道名为模型类名反斜杠替换为点. 主键例如App.Models.User.1。与之对称服务端 DatabaseNotificationsSent 事件 在broadcastOn()中采用了完全相同的命名逻辑来创建PrivateChannel并用broadcastAs()将事件名定义为database-notifications.sent。这一点与 database-notifications.blade.php 中的监听逻辑相呼应数据库通知弹层订阅该事件后会延迟 500ms 触发$wire.call($refresh)重新拉取最新通知列表从而实现新数据库通知到达后铃铛角标实时刷新。客户端如何安全地还原通知当广播负载到达浏览器时handleBroadcastNotification()会先校验format filament只有 Filament 格式的通知才会被接受随后通过Notification::fromArray()还原为完整通知对象并入队展示。这一校验避免了无关广播事件被误当作 Filament 通知渲染。验证与常见排查点完成配置后可按以下思路验证与排查连接验证打开 Pusher或所用服务端的调试控制台刷新任一 Panel 页面应观察到来自浏览器的入站 WebSocket 连接若没有优先确认 Echo 配置段是否已取消注释、VITE_*变量是否齐备。缓存问题修改config/filament.php或.env后务必执行php artisan route:clear与php artisan config:clear否则新配置不会生效。频道鉴权广播走的是PrivateChannel需要确保 Laravel 广播路由/broadcasting/auth可用且当前用户有权限订阅自己的频道。队列消费由于BroadcastNotification实现了ShouldQueue请确认队列 worker 正在运行否则通知不会真正投递。测试先行如需为广播逻辑编写自动化测试可参照 BroadcastNotificationTest.php 验证通知的序列化、通道与队列行为。相关文件索引文档主体03-broadcast-notifications.md通知核心类Notification.phpbroadcast()、toBroadcast()、getBroadcastMessage()广播通知适配类BroadcastNotification.php前端接收组件Livewire/Notifications.php 与 notifications.blade.php数据库通知刷新事件DatabaseNotificationsSent.phpEcho 客户端配置config/filament.php打包的 Echo/Pusher 客户端dist/echo.js 及其注册处 FilamentServiceProvider.php单元测试BroadcastNotificationTest.php【免费下载链接】filamentA powerful open-source UI framework for Laravel • Build and ship apps admin panels fast with Livewire项目地址: https://gitcode.com/GitHub_Trending/fi/filament创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考