1. Introduction & Use Case

In modern web applications, notifications are crucial for user engagement, system alerts, and business communication. However, building a robust notification system from scratch is time-consuming and error-prone. You need to handle multiple channels (email, SMS, Slack, push notifications), manage templates, track delivery, respect user preferences, and ensure reliability—all while maintaining clean, maintainable code.

Filament Notifier solves these challenges by providing an enterprise-grade notification system specifically designed for FilamentPHP applications. It's built for developers who need powerful notification capabilities without the complexity of building everything from scratch.

Key Value Propositions

• Multi-Channel Support: Send notifications via Email, SMS, Slack, Discord, Push, and more—all from a single API
• Template Management: Create reusable templates with dynamic variables, managed through a beautiful admin interface
• Scheduled Notifications: Send notifications at specific times or dates
• Event-Driven Architecture: Trigger notifications based on application events
• User Preferences: Allow users to control their notification preferences via REST API
• Analytics Dashboard: Comprehensive metrics with email open/click tracking
• Rate Limiting: Built-in protection against notification abuse
• Production-Ready: Fully tested, well-documented, and follows Laravel best practices

Who Should Use Filament Notifier?

This package is perfect for:

• Laravel developers using FilamentPHP for admin panels
• Teams needing enterprise-grade notifications without building custom solutions
• Projects requiring multi-channel communication (email, SMS, Slack, etc.)
• Applications with complex notification workflows
• Developers who want analytics and tracking built-in

2. Installation & Setup

Prerequisites

Before installing Filament Notifier, ensure you have:

• PHP 8.2 or higher
• Laravel 10.x or 11.x
• FilamentPHP 4.x installed and configured
• Composer installed
• A database configured (MySQL, PostgreSQL, or SQLite)

Step 1: Install the Package

Install Filament Notifier via Composer:

composer require usamamuneerchaudhary/filament-notifier

Step 2: Run the Installation Command

After installation, run the setup command to configure the package:

php artisan notifier:install

This command performs several important setup tasks:

• Publishes the configuration file to config/notifier.php
• Runs the necessary database migrations
• Creates sample notification channels (Email, SMS, Slack)
• Creates sample notification events and templates
• Sets up the basic database structure

Step 3: Register the Plugin in Filament

Add the Filament Notifier plugin to your Filament panel configuration. Open your panel provider file (typically app/Providers/Filament/AdminPanelProvider.php):

use Usamamuneerchaudhary\Notifier\FilamentNotifierPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentNotifierPlugin::make(),
        ]);
}

After registration, you'll have access to:

• Notifier Dashboard - Comprehensive analytics and metrics
• Notification Settings - Configure preferences, analytics, and rate limiting
• Notification Resources - Manage channels, events, templates, and notifications

Step 4: Configure Environment Variables

Update your .env file with your notification channel settings:

# Email Configuration
MAIL_MAILER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=your_username
MAIL_PASSWORD=your_password
MAIL_ENCRYPTION=tls
[email protected]
MAIL_FROM_NAME="Your App"

# Notifier Package Settings
NOTIFIER_EMAIL_ENABLED=true
NOTIFIER_SLACK_ENABLED=false
NOTIFIER_SMS_ENABLED=false

# Slack Configuration (if enabled)
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
SLACK_CHANNEL=#notifications

# SMS Configuration (Twilio - if enabled)
TWILIO_ACCOUNT_SID=your_account_sid
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_PHONE_NUMBER=+1234567890

Step 5: Register Facades (Optional)

After installation, run composer dump-autoload to ensure all facades are properly registered:

composer dump-autoload

3. Core Concepts

Understanding the core concepts of Filament Notifier will help you use it effectively. The package follows a service-oriented architecture with four main components:

Architecture Overview

1. Notification Channels

Channels are the delivery mechanisms for notifications. Each channel represents a different communication method:

• Email: SMTP-based email delivery
• SMS: Text messages via Twilio or similar services
• Slack: Messages sent to Slack channels via webhooks
• Discord: Messages sent to Discord channels
• Push: Mobile push notifications

Channels are stored in the notifier_channels table and can be managed through the Filament admin panel.

2. Notification Events

Events represent specific moments in your application when notifications should be sent. Examples include:

• user.registered - When a new user signs up
• order.completed - When an order is completed
• password.reset - When a password reset is requested

Events are stored in the notifier_events table and define which channels and templates to use.

3. Notification Templates

Templates define the content structure for notifications. They support:

• Dynamic variables (e.g., {{name}}, {{email}})
• Subject lines (for email)
• Content body with HTML support
• Variable documentation

Templates are stored in the notifier_templates table and are linked to specific events.

4. Notifications

Notifications are the actual messages sent to users. Each notification:

• References a template
• Targets a specific user
• Uses a specific channel
• Contains rendered content (subject and body)
• Tracks status (pending, sent, failed)
• Includes analytics data (opens, clicks)

Notifications are stored in the notifier_notifications table.

Database Structure

The package creates the following database tables (all prefixed with notifier_ to avoid conflicts):

Service-Oriented Architecture

Filament Notifier follows Laravel best practices with a clean, service-oriented architecture:

• Service Classes: Regular classes that can be dependency injected or accessed via facades
• Facades: Convenient static access to services (registered in composer.json)
• Dependency Injection: Preferred approach for controllers and testable code
• Service Container: All services are registered as singletons for optimal performance

4. Basic Usage

Sending Your First Notification

Once installed and configured, sending a notification is straightforward. Here's a basic example:

use Usamamuneerchaudhary\Notifier\Facades\Notifier;

// Send a notification using the facade
Notifier::send($user, 'user.registered', [
    'name' => $user->name,
    'email' => $user->email,
]);

This single line of code:

1. Looks up the event configuration for user.registered
2. Retrieves the associated template
3. Checks user preferences for enabled channels
4. Renders the template with provided data
5. Creates notification records for each enabled channel
6. Queues the notifications for delivery

Using Dependency Injection

For better testability, use dependency injection instead of facades:

use Usamamuneerchaudhary\Notifier\Services\NotifierManager;

class UserController extends Controller
{
    public function __construct(
        protected NotifierManager $notifier
    ) {}
    
    public function store(Request $request)
    {
        $user = User::create($request->validated());
        
        // Send welcome notification
        $this->notifier->send($user, 'user.registered', [
            'name' => $user->name,
            'email' => $user->email,
        ]);
        
        return redirect()->route('users.index');
    }
}

Creating Notification Templates

Templates can be created through the Filament admin panel or programmatically. Let's explore both approaches:

Via Admin Panel

Navigate to Notifier → Templates in your Filament admin panel and create a new template:

When creating a template, you'll need to provide:

• Template Name: A unique identifier (e.g., welcome-email)
• Linked Event: The event this template is associated with
• Subject: Email subject line (supports variables like {{name}})
• Content: The notification body (supports HTML and variables)
• Variables: Documentation of available variables

Programmatically

You can also create templates programmatically:

use Usamamuneerchaudhary\Notifier\Models\NotificationTemplate;

NotificationTemplate::create([
    'name' => 'welcome-email',
    'event_key' => 'user.registered',
    'subject' => 'Welcome to {{app_name}}, {{name}}!',
    'content' => 'Hi {{name}},

Welcome to {{app_name}}! We\'re excited to have you on board.

Best regards,
The {{app_name}} Team',
    'variables' => [
        'name' => 'User\'s full name',
        'app_name' => 'Application name',
        'email' => 'User\'s email address',
    ],
    'is_active' => true,
]);

Creating Notification Events

Events define when notifications should be sent and which channels to use. Create events through the admin panel:

When creating an event, specify:

• Event Key: Unique identifier (e.g., user.registered)
• Event Name: Display name (e.g., "User Registered")
• Group: Category for organization (e.g., "User", "Order")
• Description: What triggers this event
• Channels: Which channels to use (configured separately)

Configuring Channels

Channels are configured through the admin panel. Navigate to Notifier → Channels:

Each channel requires specific configuration:

• Email: Uses Laravel's mail configuration
• SMS: Requires Twilio credentials (or similar)
• Slack: Requires webhook URL

5. Advanced Features

Scheduled Notifications

Send notifications at specific times using the schedule() method:

use Carbon\Carbon;
use Usamamuneerchaudhary\Notifier\Facades\Notifier;

// Schedule a notification for 7 days from now
Notifier::schedule(
    $user, 
    'reminder.email', 
    Carbon::now()->addDays(7), 
    [
        'task_name' => 'Complete project review',
        'due_date' => Carbon::now()->addDays(7)->format('Y-m-d'),
    ]
);

Scheduled notifications are stored with a scheduled_at timestamp and are automatically sent when the time arrives (requires a scheduled task runner).

Event-Driven Notifications

Filament Notifier is designed to work seamlessly with Laravel's event system. You can trigger notifications from any event listener:

// In your EventServiceProvider or event listener
use Illuminate\Auth\Events\Registered;
use Usamamuneerchaudhary\Notifier\Facades\Notifier;

class SendWelcomeNotification
{
    public function handle(Registered $event)
    {
        Notifier::send($event->user, 'user.registered', [
            'name' => $event->user->name,
            'email' => $event->user->email,
        ]);
    }
}

Register the listener in your EventServiceProvider:

protected $listen = [
    Registered::class => [
        SendWelcomeNotification::class,
    ],
];

Multi-Channel Notifications

Send notifications to multiple channels simultaneously. The event configuration determines which channels are used:

// Send to all channels configured for the event
Notifier::send($user, 'order.completed', [
    'order_id' => $order->id,
    'total' => $order->total,
]);

// Or send to a specific channel only
Notifier::sendToChannel($user, 'order.completed', 'email', [
    'order_id' => $order->id,
]);

User preferences are automatically respected—if a user has disabled email notifications, they won't receive emails even if the event is configured to send emails.

User Preferences Management

Users can control their notification preferences through the REST API (discussed in detail in the API section). Administrators can also manage preferences through the Filament admin panel.

Custom Channel Drivers

Create custom channel drivers by implementing the ChannelDriverInterface:

use Usamamuneerchaudhary\Notifier\Services\ChannelDrivers\ChannelDriverInterface;
use Usamamuneerchaudhary\Notifier\Models\Notification;

class CustomChannelDriver implements ChannelDriverInterface
{
    public function send(Notification $notification): bool
    {
        // Your custom sending logic here
        // For example, send via a custom API
        
        try {
            // Send notification via your custom service
            $this->customApiService->send([
                'to' => $notification->user->email,
                'subject' => $notification->subject,
                'body' => $notification->content,
            ]);
            
            return true;
        } catch (\Exception $e) {
            \Log::error('Failed to send notification', [
                'notification_id' => $notification->id,
                'error' => $e->getMessage(),
            ]);
            
            return false;
        }
    }
    
    public function validateSettings(array $settings): bool
    {
        // Validate your channel settings
        return !empty($settings['api_key'] ?? null);
    }
}

Register your custom driver in a service provider:

use Usamamuneerchaudhary\Notifier\Facades\Notifier;

public function boot()
{
    Notifier::registerChannel('custom', CustomChannelDriver::class);
}

6. Analytics & Tracking

Filament Notifier includes comprehensive analytics tracking for email notifications, allowing you to measure engagement and optimize your notification strategy.

Email Open Tracking

When track_opens is enabled in analytics settings, a 1x1 transparent tracking pixel is automatically injected into all email notifications. When a user opens the email, the pixel loads and tracks the open event.

Tracking Endpoint:GET /notifier/track/open/{token}

This endpoint:

• Returns a 1x1 transparent PNG pixel
• Records the first open time in opened_at
• Increments the opens_count counter
• Respects analytics enabled/disabled settings

Link Click Tracking

When track_clicks is enabled, all URLs in email content are automatically rewritten to use tracking URLs. When users click links, the system tracks the click and redirects to the original URL.

Tracking Endpoint:GET /notifier/track/click/{token}?url={encoded_url}

This endpoint:

• Records the first click time in clicked_at
• Increments the clicks_count counter
• Safely redirects to the original URL
• Validates URLs to prevent open redirect vulnerabilities

Analytics Dashboard

Access the comprehensive analytics dashboard in your Filament admin panel by navigating to Notifier → Dashboard.

Dashboard Features

1. Overview Stats Widget

• Total notifications with trend chart
• Success rate percentage
• Pending notifications count
• Failed notifications count
• Active channels count

2. Engagement Stats Widget

• Total opens
• Open rate percentage
• Total clicks
• Click rate percentage
• Click-through rate

3. Time Series Chart

• 30-day line chart showing sent, opened, and clicked notifications
• Full-width visualization
• Auto-refreshes every 30 seconds

4. Engagement Analytics Chart

• Combined bar and line chart
• Shows opens and clicks
• Overlays open rate % and click rate %
• Dual Y-axis for counts and percentages
• Last 7 days view

5. Channel Performance Chart

• Bar chart comparing all active channels
• Shows sent, opened, and clicked per channel
• Helps identify best-performing channels

6. Rate Limiting Status Widget

• Real-time usage for minute, hour, and day limits
• Color-coded warnings
• Percentage usage indicators
• Auto-refreshes every 10 seconds

Rate Limiting Configuration

Configure rate limits in the Filament admin panel under Notifier → Settings → Rate Limiting:

• Max Per Minute: Maximum notifications allowed per minute (default: 60)
• Max Per Hour: Maximum notifications allowed per hour (default: 1000)
• Max Per Day: Maximum notifications allowed per day (default: 10000)

Rate limiting is enforced before notification creation. If any limit is exceeded, notification creation is blocked and the violation is logged for monitoring.

Data Retention

Configure data retention in the analytics settings. Use the cleanup command to remove old analytics data:

# Clean up analytics data older than retention period
php artisan notifier:cleanup-analytics

# Dry run to see what would be cleaned
php artisan notifier:cleanup-analytics --dry-run

The cleanup command:

• Respects the retention_days setting
• Anonymizes analytics data
• Can be scheduled via Laravel's task scheduler

Add to your app/Console/Kernel.php:

protected function schedule(Schedule $schedule)
{
    $schedule->command('notifier:cleanup-analytics')
        ->daily()
        ->at('02:00');
}

7. User Preferences API

The package provides a simple REST API for users to manage their notification preferences. All endpoints require authentication and respect the allow_override setting configured in the admin panel.

Authentication

All API endpoints require authentication. Use Laravel Sanctum, Passport, or your preferred authentication method. Include the bearer token in the Authorization header:

Authorization: Bearer {your_token}

Get All User Preferences

Endpoint:GET /api/notifier/preferences

curl -X GET https://your-app.com/api/notifier/preferences \
  -H "Authorization: Bearer {token}"

Response:

{
  "data": [
    {
      "event_key": "user.registered",
      "event_name": "User Registered",
      "event_group": "User",
      "description": "Sent when a new user registers",
      "channels": {
        "email": true,
        "sms": false,
        "push": true
      }
    }
  ]
}

Get Available Events and Channels

Endpoint:GET /api/notifier/preferences/available

curl -X GET https://your-app.com/api/notifier/preferences/available \
  -H "Authorization: Bearer {token}"

Response:

{
  "data": {
    "events": [
      {
        "key": "user.registered",
        "name": "User Registered",
        "group": "User",
        "description": "Sent when a new user registers",
        "default_channels": ["email"]
      }
    ],
    "channels": [
      {
        "type": "email",
        "title": "Email",
        "icon": "heroicon-o-envelope"
      },
      {
        "type": "sms",
        "title": "SMS",
        "icon": "heroicon-o-device-phone-mobile"
      }
    ]
  }
}

Get Preference for Specific Event

Endpoint:GET /api/notifier/preferences/{eventKey}

curl -X GET https://your-app.com/api/notifier/preferences/user.registered \
  -H "Authorization: Bearer {token}"

Response:

{
  "data": {
    "event_key": "user.registered",
    "event_name": "User Registered",
    "event_group": "User",
    "description": "Sent when a new user registers",
    "channels": {
      "email": true,
      "sms": false
    }
  }
}

Update Preference for Event

Endpoint:PUT /api/notifier/preferences/{eventKey}

curl -X PUT https://your-app.com/api/notifier/preferences/user.registered \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "channels": {
      "email": true,
      "sms": true,
      "push": false
    },
    "settings": {}
  }'

Response:

{
  "data": {
    "event_key": "user.registered",
    "event_name": "User Registered",
    "channels": {
      "email": true,
      "sms": true,
      "push": false
    }
  },
  "message": "Preferences updated successfully."
}

Error Responses

• 403 Forbidden: User preference override is disabled by administrator
• 422 Unprocessable Entity: Invalid channel type or validation error
• 404 Not Found: Event not found or inactive

Use Cases

The User Preferences API is perfect for:

• Mobile Apps: Allow users to manage notification preferences from their mobile app
• Frontend Integration: Build preference management UI in your frontend application
• Third-Party Integrations: Allow external services to manage user preferences
• User Self-Service: Enable users to control their notification experience

8. Real-World Examples

Example 1: User Registration Welcome Email

Send a welcome email when a new user registers:

use Illuminate\Auth\Events\Registered;
use Usamamuneerchaudhary\Notifier\Facades\Notifier;

class SendWelcomeNotification
{
    public function handle(Registered $event)
    {
        Notifier::send($event->user, 'user.registered', [
            'name' => $event->user->name,
            'email' => $event->user->email,
            'app_name' => config('app.name'),
            'login_url' => route('login'),
        ]);
    }
}

Template Example:

Subject: Welcome to {{app_name}}, {{name}}!

Hi {{name}},

Welcome to {{app_name}}! We're excited to have you on board.

Your account has been successfully created with the email: {{email}}

You can log in at any time: {{login_url}}

Best regards,
The {{app_name}} Team

Example 2: Order Confirmation (Multi-Channel)

Send order confirmation via email and SMS:

use Usamamuneerchaudhary\Notifier\Facades\Notifier;

class OrderController extends Controller
{
    public function complete(Order $order)
    {
        $order->update(['status' => 'completed']);
        
        // Send multi-channel notification
        Notifier::send($order->user, 'order.completed', [
            'order_id' => $order->id,
            'order_number' => $order->order_number,
            'total' => $order->formatted_total,
            'items_count' => $order->items->count(),
            'tracking_url' => route('orders.tracking', $order),
        ]);
        
        return redirect()->route('orders.show', $order);
    }
}

Configure the event to use both email and SMS channels in the admin panel. The system will automatically send to both channels if the user has them enabled.

Example 3: Scheduled Reminder Notifications

Send a reminder 24 hours before a scheduled event:

use Carbon\Carbon;
use Usamamuneerchaudhary\Notifier\Facades\Notifier;

class EventController extends Controller
{
    public function store(Request $request)
    {
        $event = Event::create($request->validated());
        
        // Schedule reminder for 24 hours before event
        $reminderTime = Carbon::parse($event->start_time)->subDay();
        
        foreach ($event->attendees as $attendee) {
            Notifier::schedule($attendee->user, 'event.reminder', $reminderTime, [
                'event_name' => $event->name,
                'event_date' => $event->start_time->format('F j, Y'),
                'event_time' => $event->start_time->format('g:i A'),
                'event_location' => $event->location,
                'event_url' => route('events.show', $event),
            ]);
        }
        
        return redirect()->route('events.show', $event);
    }
}

Example 4: Password Reset Notification

Send password reset notification with security information:

use Illuminate\Auth\Events\PasswordReset;
use Usamamuneerchaudhary\Notifier\Facades\Notifier;

class SendPasswordResetNotification
{
    public function handle(PasswordReset $event)
    {
        Notifier::send($event->user, 'password.reset', [
            'name' => $event->user->name,
            'ip_address' => request()->ip(),
            'user_agent' => request()->userAgent(),
            'reset_time' => now()->format('F j, Y \a\t g:i A'),
            'support_email' => config('mail.support_email'),
        ]);
    }
}

Example 5: Admin Alert via Slack

Send critical alerts to administrators via Slack:

use Usamamuneerchaudhary\Notifier\Facades\Notifier;

class SystemAlertService
{
    public function sendCriticalAlert(string $message, array $context = [])
    {
        $admin = User::where('email', config('app.admin_email'))->first();
        
        if ($admin) {
            Notifier::sendToChannel($admin, 'system.alert', 'slack', [
                'message' => $message,
                'severity' => 'critical',
                'context' => $context,
                'timestamp' => now()->toIso8601String(),
            ]);
        }
    }
}

9. Best Practices & Tips

Template Variable Management

• Document Variables: Always document available variables in the template's variables field. This helps other developers understand what data is available.
• Use Descriptive Names: Use clear, descriptive variable names (e.g., {{order_total}} instead of {{total}}).
• Provide Defaults: Consider providing default values for optional variables to prevent empty content.
• Validate Variables: Always validate that required variables are present before sending notifications.

Rate Limiting Strategies

• Monitor Usage: Regularly check the rate limiting status widget in the dashboard to understand your notification patterns.
• Adjust Limits: Set limits based on your actual usage patterns and provider constraints (e.g., email service limits).
• Handle Failures: Implement retry logic for failed notifications, but respect rate limits.
• Queue Management: Use separate queues for different notification priorities to prevent blocking.

Analytics Data Retention

• Set Appropriate Retention: Configure retention based on your business needs. 90 days is a good default for most applications.
• Schedule Cleanup: Set up automated cleanup via Laravel's scheduler to prevent database bloat.
• Export Before Cleanup: If you need historical data, export it before running cleanup.
• Monitor Storage: Keep an eye on database size as analytics data can grow quickly.

Performance Considerations

• Use Queues: Always use queues for notification sending to prevent blocking HTTP requests.
• Batch Operations: When sending to multiple users, consider batching to avoid overwhelming the queue.
• Cache Templates: Enable template caching in production for better performance.
• Database Indexing: Ensure proper indexes on frequently queried columns (user_id, status, scheduled_at).
• Monitor Queue Workers: Ensure you have enough queue workers to handle notification volume.

Security Best Practices

• Validate User Input: Always validate and sanitize user-provided data before using it in templates.
• Protect API Endpoints: Ensure API endpoints are properly authenticated and rate-limited.
• Sanitize URLs: The package automatically validates URLs in click tracking to prevent open redirect vulnerabilities.
• Review Permissions: Regularly review who has access to notification settings and templates.

Testing Notifications

Use the provided test command to verify your notification setup:

# Send a test notification
php artisan notifier:test user.registered --user=1

# Send with custom data
php artisan notifier:test user.registered --user=1 \
  --data="name=John Doe" \
  --data="app_name=Test App"

# Send to specific channel
php artisan notifier:test user.registered --user=1 --channel=email

Error Handling

• Log Failures: Failed notifications are automatically logged. Monitor these logs regularly.
• Retry Logic: Implement retry logic for transient failures (network issues, temporary service outages).
• Fallback Channels: Consider implementing fallback channels for critical notifications.
• Alert on Failures: Set up alerts for high failure rates to catch issues early.

10. Conclusion

Filament Notifier provides a comprehensive, production-ready solution for managing notifications in your FilamentPHP applications. With its multi-channel support, template management, analytics tracking, and user preferences API, it handles the complexity of notification systems so you can focus on building great features.

Key Benefits Summary

• ✅ Easy Installation: Get started in minutes with a single command
• ✅ Multi-Channel Support: Send notifications via email, SMS, Slack, and more
• ✅ Template Management: Create and manage templates through a beautiful admin interface
• ✅ Analytics Dashboard: Track opens, clicks, and engagement metrics
• ✅ User Preferences: Let users control their notification experience
• ✅ Rate Limiting: Built-in protection against abuse
• ✅ Production-Ready: Fully tested and following Laravel best practices

When to Use Filament Notifier

Consider using Filament Notifier if you:

• Need to send notifications via multiple channels
• Want analytics and tracking for your notifications
• Need to manage notification templates through an admin interface
• Want to allow users to control their notification preferences
• Need scheduled notifications
• Want a production-ready solution without building from scratch

Next Steps

1. Install the package and run through the setup process
2. Create your first notification template and event
3. Send a test notification to verify everything works
4. Explore the analytics dashboard
5. Integrate notifications into your application workflows
6. Configure user preferences API for your frontend

Resources

• Package:Packagist
• GitHub:Repository
• Documentation: See the README.md for complete API reference
• Support: Open an issue on GitHub or contact [email protected]