Filament Alerts Laravel Package

Technical Evaluation

Architecture Fit

• Filament Integration: The package is tightly coupled with Filament (Laravel admin panel), leveraging its native notification system. This makes it ideal for projects already using Filament for admin interfaces, as it extends existing workflows without reinventing notification logic.
• Multi-Channel Support: Supports email, FCM (Firebase Cloud Messaging), and potentially other drivers via Laravel’s notification system. This aligns well with modern SPAs (via FCM) and traditional web apps (email).
• Template-Based: Uses notification templates, reducing boilerplate for common alerts (e.g., "Your password was reset"). This is a strong fit for admin dashboards where consistency is key.
• Macro Extensibility: Leverages Laravel’s notification macros, allowing customization without modifying core logic. This is low-risk for future-proofing.

Integration Feasibility

• Laravel Ecosystem Compatibility: Works seamlessly with Laravel 10+ and Filament 3.x. If the project uses these, integration is straightforward (composer install + config).
• FCM Dependency: Requires Firebase setup for push notifications. If the project already uses Firebase (e.g., for mobile apps), this is a non-issue. Otherwise, adds moderate complexity.
• Database Requirements: Likely stores templates/alerts in the DB (Filament’s native notifications use notifications table). Ensure the project’s DB schema supports this.
• Authentication Sync: Alerts are user-specific. Must ensure Filament’s auth system (e.g., Laravel Breeze/Sanctum) is properly configured to map users to notification channels.

Technical Risk

• Filament Version Lock: Package is Filament 3.x-specific. If the project uses an older/new version, migration risk exists.
• FCM Configuration: Push notifications require Firebase setup, which may introduce CORS, service worker, or backend API complexities if not already in place.
• Template Customization: Overriding default templates may require Blade/JS tweaks, adding minor dev effort.
• Testing Overhead: New notification channels (e.g., FCM) may need end-to-end testing for delivery reliability.

Key Questions

1. Does the project use Filament 3.x? If not, what’s the upgrade path?
2. Are push notifications (FCM) a requirement? If yes, is Firebase already configured?
3. How are user notifications currently handled? Will this replace existing systems or augment them?
4. What’s the alert volume? High-throughput systems may need queue workers (e.g., Laravel Horizon) for reliability.
5. Are there compliance concerns? (e.g., GDPR for user notifications, FCM data handling)

Integration Approach

Stack Fit

• Primary Fit: Laravel + Filament projects needing scalable, multi-channel alerts with minimal boilerplate.
• Secondary Fit: Projects using Firebase for push notifications and wanting to unify web/mobile alerts.
• Non-Fit: Non-Filament Laravel apps (would need custom UI layers) or projects without Firebase.

Migration Path

1. Assessment Phase:
   • Audit existing notification logic (e.g., custom email queues, manual FCM calls).
   • Verify Filament version compatibility.
2. Pilot Integration:
   • Install package (composer require tomatophp/filament-alerts).
   • Configure FCM credentials (if using push) via .env.
   • Set up notification templates in Filament’s UI.
3. Phased Rollout:
   • Phase 1: Replace simple email alerts with the package’s templated system.
   • Phase 2: Add FCM for mobile users (if applicable).
   • Phase 3: Deprecate legacy notification code.

Compatibility

• Laravel: Tested on Laravel 10+. Ensure laravel/framework and filament/filament versions are compatible.
• Filament: Must use Filament 3.x. Check for breaking changes in minor updates.
• FCM: Requires:
  • Firebase project with web app and cloud messaging enabled.
  • Service worker registered in the frontend (if using web push).
  • Backend API to handle FCM tokens (if dynamic).
• Database: Uses Filament’s native notifications table. No schema migrations required unless customizing.

Sequencing

1. Backend Setup:
   • Install package and publish config (php artisan vendor:publish --provider="Tomato\FilamentAlerts\FilamentAlertsServiceProvider").
   • Configure FCM (if needed) in .env:

     FCM_KEY=your_key
     FCM_PROJECT_ID=your_project
     

2. Template Configuration:
   • Define templates in Filament’s UI or via migrations.
   • Example template (Blade):

     <h1>{{ $alert->title }}</h1>
     <p>{{ $alert->message }}</p>
     

3. Channel Configuration:
   • Register channels in config/filament-alerts.php:

     'channels' => [
         'mail' => true,
         'fcm' => env('FCM_ENABLED', false),
     ],
     

4. Frontend (FCM Only):
   • Ensure service worker is registered for push notifications.
   • Handle token storage (e.g., sync with user model).
5. Testing:
   • Test email delivery (simple).
   • Test FCM with Firebase Console and Postman (for API-triggered alerts).
   • Load test with high-volume alerts (if applicable).

Operational Impact

Maintenance

• Pros:
  • MIT License: No vendor lock-in.
  • Active Maintenance: Recent releases (2025) and CI/CD pipelines (Dependabot, tests).
  • Filament Alignment: Updates will sync with Filament’s roadmap.
• Cons:
  • FCM Dependency: Firebase’s pricing/model may change, affecting push notifications.
  • Template Updates: Custom templates may need updates if Filament’s notification system evolves.

Support

• Documentation: README is basic but functional. Expect to rely on:
  • Filament’s docs for notification system quirks.
  • GitHub issues for package-specific bugs.
• Community: Small but responsive (81 stars, MIT license encourages contributions).
• Debugging:
  • Use Laravel’s NotificationFailed events to log failures.
  • FCM issues may require Firebase’s debugging tools.

Scaling

• Performance:
  • Email: Laravel’s queue system (e.g., mail:work) handles volume well.
  • FCM: Firebase has rate limits (~240 messages/minute per project). For high volume:
    • Use batch sending (e.g., chunk users).
    • Monitor Firebase’s quota page.
• Database:
  • Notification storage grows with usage. Archive old alerts if needed.
• Cost:
  • FCM: Free tier covers ~1M messages/month. Beyond that, pay-as-you-go.
  • Email: Depends on SMTP provider (e.g., Mailgun, SendGrid).

Failure Modes

Ramp-Up

• Developer Onboarding:
  • 1–2 hours: Install and configure basic email alerts.
  • 4–6 hours: Add FCM and test push notifications (including frontend setup).
  • 1 day: Customize templates and handle edge cases (e.g., user-specific channels).
• Key Learning Curve:
  • Understanding Filament’s notification system (e.g., notify() vs. routeNotificationFor()).
  • FCM token management (how to sync tokens with user accounts).
• Training Needs:
  • Frontend devs: Service worker registration and push event handling.
  • Backend devs: Laravel notification channels and queue workers.