包简介

Admin notification management system for FilamentPHP

README 文档

README

A FilamentPHP v3 package for creating and managing custom notifications sent to users through your admin panel. Send database and email notifications with read tracking, customizable templates, and full Shield integration.

Features

Database & Email Delivery - Send notifications via database (notification bell) or email
Custom Email Templates - Create and manage custom email templates with full Blade support
Draft & Send Workflow - Save as draft, review, then send when ready
Read Tracking - Track which users have read each notification
Multi-User Selection - Send to one or multiple users at once
Customizable Appearance - Choose from 13+ heroicons and colors
Shield Integration - Full permission system integration
Soft Deletes - Complete audit trail with soft delete support

Requirements

PHP 8.2+
Laravel 11.0+
FilamentPHP 3.2+

Installation

1. Install via Composer

composer require zynqa/filament-notifications

2. Run Migrations

php artisan migrate

This creates:

admin_notifications - Notification content and metadata
notification_recipients - Recipient tracking with read status
notification_settings - Email template preferences

3. Register Plugin

Add to your Filament Panel Provider (e.g., app/Providers/Filament/AppPanelProvider.php):

use Zynqa\FilamentNotifications\FilamentNotificationsPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentNotificationsPlugin::make(),
        ])
        ->databaseNotifications(); // Required for notification bell
}

4. Add User Model Relationships

Add to app/Models/User.php:

use Zynqa\FilamentNotifications\Models\AdminNotification;

public function adminNotifications(): \Illuminate\Database\Eloquent\Relations\BelongsToMany
{
    return $this->belongsToMany(AdminNotification::class, 'notification_recipients')
        ->withPivot('read_at')
        ->withTimestamps()
        ->orderByPivot('created_at', 'desc');
}

public function unreadAdminNotifications(): \Illuminate\Database\Eloquent\Relations\BelongsToMany
{
    return $this->adminNotifications()->wherePivotNull('read_at');
}

5. Configure Permissions (Optional)

If using Filament Shield:

php artisan shield:generate --all

Then assign admin::notification permissions to roles via the Shield UI.

Usage

Creating and Sending Notifications

Navigate to Notifications in your admin panel
Click Create
Fill in the form:
- Title - Brief headline
- Body - Detailed message
- Delivery Method - Database (bell) or Email & Database
- Type - Info, Success, Warning, or Danger
- Icon & Color - Choose from available options
- Recipients - Select one or more users
Click Create (saves as draft)
Review and click Send Notification

Recipients will see the notification in their notification bell (database) or receive an email, depending on the delivery method selected.

Email Templates

Using Existing Templates

Navigate to Settings → General Settings
Scroll to Notification Settings
Select your preferred template from the dropdown
Click Save

Creating Custom Templates

Email templates are stored in storage/app/mail-templates/ and are automatically discovered.

Step 1: Create a new Blade file in storage/app/mail-templates/

Example: storage/app/mail-templates/urgent-alert.blade.php

Step 2: Use the available variables in your template:

<!DOCTYPE html>
<html>
<head>
    <title>{{ $title }}</title>
    <style>
        body { font-family: Arial, sans-serif; }
        .container { max-width: 600px; margin: 0 auto; padding: 20px; }
        .alert {
            background-color: {{ $notification_type === 'danger' ? '#fee' : '#efe' }};
            padding: 20px;
            border-radius: 8px;
        }
    </style>
</head>
<body>
    <div class="container">
        <div class="alert">
            <h1>{{ $title }}</h1>
            <p>{!! nl2br(e($body)) !!}</p>

            @if($url)
                <a href="{{ $url }}" style="display: inline-block; padding: 10px 20px;
                   background: #3b82f6; color: white; text-decoration: none;
                   border-radius: 5px;">View Details</a>
            @endif
        </div>

        <footer style="margin-top: 30px; text-align: center; color: #6b7280;">
            <p>{{ config('app.name') }}</p>
        </footer>
    </div>
</body>
</html>

Available Variables:

$title (string) - Notification title
$body (string) - Notification body text
$url (string|null) - Optional action URL
$notification_type (string) - 'info', 'success', 'warning', or 'danger'
$icon (string) - Heroicon name (e.g., 'heroicon-o-bell')
$icon_color (string) - 'primary', 'success', 'warning', 'danger', 'info', or 'gray'

Step 3: Save the file

The template will automatically appear in the General Settings dropdown with a formatted name (e.g., "Urgent Alert").

Tips:

Use inline CSS for best email client compatibility
Always escape user content with e() or {!! nl2br(e($body)) !!}
Test across different email clients
Keep designs simple and mobile-friendly

Configuration

Optionally publish the config file:

php artisan vendor:publish --tag="filament-notifications-config"

Customize navigation, permissions, and icons in config/filament-notifications.php.

Permissions

When using Filament Shield, these permissions are created:

view_any_admin::notification - View notifications list
view_admin::notification - View individual notification
create_admin::notification - Create new notifications
update_admin::notification - Edit drafts
delete_admin::notification - Delete drafts
restore_admin::notification - Restore soft-deleted notifications
force_delete_admin::notification - Permanently delete notifications

Note: Sent notifications are read-only and cannot be edited or deleted.

Support

Issues: GitHub Issues
Email: info@zynqa.com

License

MIT License. See LICENSE.md for details.

zynqa/filament-notifications 适用场景与选型建议

zynqa/filament-notifications 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 40 次下载、GitHub Stars 达 0，最近一次更新时间为 2026 年 02 月 16 日，在 PHP 生态内属于活跃度较高的组件。

我们在过去多个企业项目中使用过 zynqa/filament-notifications 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 zynqa/filament-notifications 我们能提供哪些服务？

定制开发 / 二次开发

基于 zynqa/filament-notifications 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

zynqa/filament-notifications

包简介