Filament Webpush Laravel Package

Technical Evaluation

Architecture Fit

• Filament Integration: Designed specifically for Filament, a modern admin panel framework for Laravel, making it a perfect fit for projects already using Filament. Leverages Filament’s resource/panel system for seamless UI integration.
• Web Push Abstraction: Encapsulates Web Push Protocol (W3C standard) complexity, abstracting away service worker registration, subscription management, and push payload formatting. Ideal for projects requiring real-time notifications without deep browser API expertise.
• Laravel Ecosystem Compatibility: Built on Laravel’s service container, events, and queue systems, ensuring native integration with existing Laravel applications (e.g., queues for async push delivery, events for subscription lifecycle hooks).
• Modular Design: Lightweight (~500 LOC) with clear separation of concerns (e.g., PushService, SubscriptionManager), enabling selective adoption (e.g., only use push notifications without full Filament admin).

Integration Feasibility

• Low-Coupling: Uses Filament’s service providers and widgets for integration, minimizing invasive changes. Can be added as a standalone package without modifying core Filament logic.
• Dependency Alignment:
  • Requires Filament v3.x (check compatibility with your Filament version).
  • Depends on web-push PHP library (for server-side push handling) and filament/support (for Filament-specific utilities).
  • No database migrations required (uses Filament’s built-in storage or customizable storage adapters).
• Frontend Requirements:
  • Service worker registration (handled via Filament’s asset pipeline or custom JS).
  • Browser API support (Chrome/Firefox/Safari with PWA enabled).
  • No jQuery/legacy JS dependency—modern ES6+.

Technical Risk

Key Questions

1. Filament Version:

   • What version of Filament are you using? Does it support Filament v3.x?
   • Are there plans to upgrade/downgrade Filament soon?

2. Push Use Cases:

   • Will notifications be user-specific (e.g., alerts) or system-wide (e.g., admin alerts)?
   • Do you need rich notifications (images/buttons) or simple text?

3. Infrastructure:

   • Do you have a TLS certificate for your domain (required for Web Push)?
   • Is your Laravel app behind a reverse proxy (e.g., Nginx)? If so, ensure /_ah/queue/push is exposed.

4. Frontend Setup:

   • How will service workers be registered (custom JS or Filament’s asset pipeline)?
   • Do you need to support legacy browsers (e.g., IE11)?

5. Scaling:

   • What’s the expected daily active users (DAU) for push notifications?
   • Are you using Laravel Horizon or another queue system?

6. Monitoring:

   • How will you track delivery success/failure rates (e.g., failed subscriptions)?
   • Do you need analytics on notification engagement (e.g., click-through rates)?

Integration Approach

Stack Fit

• Primary Stack:
  • Backend: Laravel 10+ with Filament v3.x.
  • Frontend: Modern SPAs (Vue/React) or server-rendered Blade (Filament’s default).
  • Infrastructure: Any Laravel-compatible host (shared/VPS/cloud) with TLS.
• Secondary Stack:
  • Queue Workers: Laravel’s queue:work or Horizon for async pushes.
  • Database: Supports Filament’s default storage (SQLite/MySQL/Postgres) or custom adapters (e.g., Redis for subscriptions).
  • CDN: Optional for service worker assets (e.g., hosted on Filament’s asset pipeline).

Migration Path

1. Prerequisites:

   • Ensure Filament is installed (composer require filament/filament).
   • Generate VAPID keys (use the package’s php artisan filament-webpush:generate-keys).
   • Configure TLS for your domain (e.g., Let’s Encrypt).

2. Installation:

   composer require andrefelipe18/filament-webpush
   php artisan vendor:publish --provider="Andrefelipe18\FilamentWebpush\FilamentWebpushServiceProvider"
   

   • Publish config (config/filament-webpush.php) and update with your VAPID keys.

3. Frontend Setup:

   • Register the service worker in your Filament panel’s JS:

     import { registerServiceWorker } from 'filament-webpush';
     registerServiceWorker('/service-worker.js');
     

   • Or use Filament’s asset pipeline to auto-register.

4. Backend Integration:

   • Option A: Use Filament’s Widgets to display subscription prompts:

     use Andrefelipe18\FilamentWebpush\Widgets\PushSubscriptionWidget;
     PushSubscriptionWidget::make()->subscribeUsers();
     

   • Option B: Manually trigger pushes via PushService:

     use Andrefelipe18\FilamentWebpush\Facades\PushService;
     PushService::send('Welcome!', ['user_id' => 1]);
     

5. Testing:

   • Use Chrome DevTools to test push notifications (Application > Service Workers).
   • Verify subscriptions are stored in filament_webpush_subscriptions table (or custom adapter).

Compatibility

Sequencing

1. Phase 1: Setup (1-2 days)

   • Install package, configure VAPID keys, and set up TLS.
   • Integrate service worker registration into Filament’s frontend.

2. Phase 2: Core Functionality (2-3 days)

   • Add subscription widget to Filament dashboard.
   • Implement basic push triggers (e.g., user login, admin actions).

3. Phase 3: Advanced Features (3-5 days)

   • Customize notification payloads (e.g., dynamic data from Laravel models).
   • Set up queue workers for async pushes.
   • Add monitoring (e.g., track failed subscriptions).

4. Phase 4: Optimization (Ongoing)

   • A/B test notification timing/content.
   • Optimize service worker caching for offline support.

Operational Impact

Maintenance

• Package Updates:
  • Monitor andrefelipe18/filament-webpush for updates (MIT license allows forks if needed).
  • Critical: Watch for Filament v4.x compatibility (if released).
• Dependency Management:
  • web-push PHP library may require updates for security patches (e.g., VAPID key rotation).
  • Pin versions in composer.json to avoid breaking changes:

    "andrefelipe18/filament-webpush": "^1.0",
    "web-push": "^5.0"
    

• Configuration Drift:
  • Store VAPID keys in .env (never in Git).
  • Use Filament’s config caching (php artisan config:cache) in production.

Support

• Troubleshooting:
  • Common Issues:
    • "Blocked by CORS": Ensure service worker scope matches your domain.