Filament Push Notifications Laravel Package

Getting Started

• Install the major version explicitly: composer require xentixar/filament-push-notifications:^2.0. v2.0.0 adds Filament v5 support and web push via service workers, so confirm your panel’s Filament version matches the package constraints before upgrading.
• Publish and run the package assets:
  • php artisan vendor:publish --tag="filament-push-notifications-config"
  • php artisan vendor:publish --tag="filament-push-notifications-migrations" then php artisan migrate
  • Publish any frontend/service-worker assets using the tag documented in the README (v2 introduces a service worker, so expect a public/sw.js or similar publish step).
• Generate and configure VAPID keys. Web push requires a public/private key pair; the package likely exposes an artisan command or config keys. Put the private key in .env, expose only the public key to the browser.
• Register the plugin in your Filament panel provider:

  ->plugin(PushNotificationsPlugin::make())
  

• Register the service worker on the pages where users should receive notifications. Check the README for the recommended Blade directive, Filament render hook, or script tag. The service worker must be served from the site root (or the correct scope) to control the page.
• First use case: open the Filament admin page provided by the plugin, subscribe your browser, and send a test notification to yourself. If the plugin does not include a test UI, trigger a notification from tinker or a simple route using the package’s notification builder.

Where to look first: the README’s v2 upgrade section, config/filament-push-notifications.php, the published service worker, the migrations for push subscriptions, and the Filament plugin class/page registered by the package.

Implementation Patterns

• Sending notifications from Filament: use the package’s Filament page or resource to compose and send notifications to selected users. For programmatic sends, use the package’s notification class/builder rather than raw web-push calls so payload shape, icons, and actions stay consistent.
• Targeting subscribers: the package likely stores browser push subscriptions in a model/table. Send to a specific Filament user, a role, or all subscribers by querying that model or using the package’s scopes. Keep targeting logic in a service/action class so it can be reused from jobs and artisan commands.
• Queue long-running sends: sending to many subscriptions is I/O-bound. Wrap broadcasts in queued jobs and consider chunking subscriptions. Check whether the package already queues by default; if not, dispatch your own job.
• Subscription lifecycle: expose an endpoint or Filament page action that saves the browser’s PushSubscription JSON after the user grants permission. On logout or user deletion, clean up subscriptions. Handle stale endpoints by deleting subscriptions on 410 Gone / 404 responses.
• Custom payloads: use the package’s payload builder for title, body, icon, badge, URL, and actions. If you need custom data, keep it small and JSON-serializable; the service worker must read it from the push event.
• Integration with Laravel notifications: if the package integrates with Laravel’s notification system, create a notification class and add the package’s channel. This lets you use Notification::send() and standard queueing. If it does not, wrap the package’s sender in your own notification-like class.
• Filament v5: register the plugin in the panel provider as usual, but verify any panel configuration differences for v5. Run php artisan filament:assets after publishing assets, and clear cached views/config in deployment.
• Local development: web push generally requires HTTPS; localhost is usually exempt. Use a secure tunnel for testing on real devices, and keep separate VAPID keys per environment so production subscriptions are not invalidated by local testing.

Gotchas and Tips

• Major version bump: v2.0.0 is a major release. The service-worker implementation and Filament v5 support may include breaking changes to config keys, plugin registration, published assets, or the subscription model. Read the full changelog and upgrade notes before updating an existing v1 app.
• Filament version constraints: “Add Filament v5 support” may mean v2 drops older Filament versions. Check composer.json constraints; mixing a Filament v4 panel with this package version can cause container or asset errors.
• Service worker scope and caching: the service worker must be served from the root or a path that covers the pages it controls. Do not cache the service worker aggressively during development; use cache-busting or “Update on reload” in DevTools. A stale service worker is a common reason push events do not appear.
• VAPID key rotation: changing VAPID keys invalidates existing browser subscriptions. Treat keys as environment secrets and avoid regenerating them casually. The public key must match the private key used by the backend.
• Permission UX: browsers require a user gesture before showing the notification permission prompt. Do not request permission on page load. If permission is denied, the user must reset it in browser settings; provide clear UI feedback.
• HTTPS requirement: web push will not work over plain HTTP except on localhost. Ensure production and staging use valid TLS certificates, and that the service worker is served with the correct Content-Type and no redirects that change its scope.
• Queue and rate limits: push services can rate-limit or reject bursts. Queue sends, add retries/backoff, and log failures per subscription. Prune invalid subscriptions regularly.
• Debugging: use browser DevTools → Application → Service Workers and Push Messaging to inspect registration and subscription state. Check Laravel logs for VAPID/signature errors. Add a test artisan command or route that sends a notification to the current user before wiring up complex targeting.
• Extension points: look for custom payload classes, event listeners around subscription creation/deletion, and the ability to override the published service worker. If the package’s service worker is too opinionated, keep a thin custom sw.js that imports or mirrors the package’s push handler so you can add analytics or deep-link logic.
• Deployment: republish assets and service worker on deploy, run migrations, and clear config/view/route caches. Because the service worker lives in public/, ensure your deploy pipeline does not delete it or serve an old cached version.