Webpush Laravel Package

Technical Evaluation

Architecture Fit

• Seamless Laravel Integration: The package leverages Laravel’s native notification system, making it a natural fit for applications already using Laravel’s Notification facade. It extends the existing via() method pattern, requiring minimal architectural changes.
• Modular Design: The package follows Laravel’s conventions (traits, service providers, migrations) and integrates cleanly with Eloquent models. The HasPushSubscriptions trait enables polymorphic usage across multiple models (e.g., User, Device, or custom Notifiable models).
• Event-Driven Extensibility: Supports custom events (NotificationSent, NotificationFailed) for observability and extensibility, aligning with Laravel’s event system.
• Declarative vs. Programmatic: Offers both traditional WebPushMessage and experimental Declarative Web Push (W3C standard), allowing TPMs to choose based on browser support and feature requirements.

Integration Feasibility

• Low Friction: Requires only:
  1. Composer install.
  2. Trait addition to target models.
  3. Migration/publish config.
  4. VAPID key generation (one-time setup).
• Browser API Dependency: Relies on the Push API (Chrome/Firefox/Edge/Safari) and Service Workers, which may require frontend changes (e.g., subscription registration logic in JavaScript). Safari (iOS) has stricter requirements (e.g., VAPID_SUBJECT).
• Backend-Only Feasibility: If the frontend is already handling subscriptions (e.g., via a third-party SDK), the package can be used purely for sending notifications without additional frontend work.

Technical Risk

• Browser Compatibility:
  • Safari/iOS: Mandates VAPID_SUBJECT (valid domain/email) and may reject requests without it (e.g., BadJwtToken errors). Requires testing on real devices.
  • Declarative Web Push: Limited browser support (experimental); may need fallback logic for traditional messages.
• VAPID Key Management:
  • Keys must be immutable (rotating them breaks existing subscriptions). Store securely (e.g., AWS Secrets Manager, HashiCorp Vault).
  • Private key exposure in .env is a risk; consider environment-specific key management.
• Subscription Expiry:
  • Automatic cleanup of expired subscriptions (via ReportHandler) is enabled by default but may need tuning for high-volume apps (e.g., batch processing).
• Payload Size Limits:
  • Web Push has a 4KB payload limit (including encryption overhead). Large data (e.g., JSON) may require URL redirection or base64 encoding.
• Rate Limiting:
  • Browsers may throttle push notifications (e.g., Chrome’s background sync limits). Monitor NotificationFailed events for throttling.

Key Questions for TPM

1. Frontend Readiness:
   • Is the frontend already handling Push API subscriptions? If not, what’s the timeline for implementing subscription registration (JavaScript + Service Worker)?
   • Are users on Safari/iOS? If yes, is VAPID_SUBJECT configured and tested?
2. Key Management:
   • How will VAPID keys be stored and rotated (if ever)? Are environment-specific keys needed (e.g., dev/staging/prod)?
3. Scaling Assumptions:
   • What’s the expected volume of push notifications? Are there concerns about rate limiting or payload size?
4. Fallback Strategy:
   • Should traditional WebPushMessage be the primary channel, with Declarative Web Push as an opt-in feature?
5. Analytics/Observability:
   • Are NotificationSent/NotificationFailed events being logged/monitored? What’s the SLA for handling failed notifications?
6. Compliance:
   • Does the app need to comply with GDPR/CCPA for push notifications? The package doesn’t handle opt-outs; this must be managed at the model level (e.g., soft-deleting subscriptions).

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Native Support: Works with Laravel 12/13 (PHP 8.2+). Drop-in replacement for existing notification channels (e.g., Mail, Slack).
  • Queue Integration: Notifications sent via queues (e.g., bus:queue) will work as expected.
  • Testing: Uses Laravel’s NotificationTestCase and PHPUnit; easy to mock in tests.
• Frontend Requirements:
  • Push API: Requires Service Worker registration and subscription handling in JavaScript. Example:

    navigator.serviceWorker.register('/sw.js').then(reg => {
      reg.pushManager.subscribe({ userVisibleOnly: true })
        .then(sub => fetch('/api/subscribe', { method: 'POST', body: JSON.stringify(sub) }));
    });
    

  • Service Worker: Must handle push events and show notifications. Example:

    self.addEventListener('push', event => {
      event.waitUntil(clients.matchAll({ type: 'window' }).then(clients => {
        clients.forEach(client => client.postMessage(event.data.json()));
      }));
    });
    

• Infrastructure:
  • No external dependencies beyond Laravel’s HTTP client (for sending push messages). Firewalls may block ports 80/443 if sending to custom domains.

Migration Path

1. Phase 1: Setup (1–2 days)
   • Install package and publish config/migration.
   • Generate VAPID keys (php artisan webpush:vapid).
   • Add HasPushSubscriptions trait to target models (e.g., User).
   • Run migrations.
   • Configure config/webpush.php (e.g., padding, TTL, VAPID_SUBJECT for Safari).
2. Phase 2: Frontend Integration (2–5 days)
   • Implement Push API subscription logic in JavaScript.
   • Register Service Worker and handle push events.
   • Add endpoint to store subscriptions (e.g., /api/subscribe).
3. Phase 3: Notification Implementation (1–3 days)
   • Create notification classes extending Notification.
   • Use WebPushChannel and WebPushMessage/DeclarativeWebPushMessage.
   • Test with php artisan notify:test (if using Laravel’s testing helpers).
4. Phase 4: Monitoring (Ongoing)
   • Set up listeners for NotificationSent/NotificationFailed.
   • Monitor expired subscriptions and cleanup jobs.

Compatibility

• Laravel Versions: Officially supports 12/13 (PHP 8.2+). Laravel 11 support dropped in v11.0.0.
• Browser Support:
  • Traditional Web Push: Chrome, Firefox, Edge, Safari (with VAPID_SUBJECT).
  • Declarative Web Push: Limited support; test thoroughly.
• Backend Compatibility:
  • Works with any database Laravel supports (MySQL, PostgreSQL, SQLite).
  • Customizable table/connection via config.

Sequencing

1. Critical Path:
   • VAPID key generation → Frontend subscription logic → Backend notification setup.
2. Parallel Tasks:
   • Frontend devs implement Service Worker/subscription logic.
   • Backend TPM configures Laravel notifications and tests locally.
3. Depends On:
   • Frontend must register subscriptions before backend can send notifications.
   • Safari testing must occur early due to VAPID_SUBJECT requirements.

Operational Impact

Maintenance

• Key Rotation:
  • Risk: Rotating VAPID keys breaks existing subscriptions. Plan for long-term key stability unless a migration strategy is implemented (e.g., dual keys during transition).
  • Mitigation: Document keys as immutable; use environment-specific keys for staging/prod.
• Subscription Cleanup:
  • Automatic expiry detection is enabled by default but may need tuning for large-scale apps (e.g., batch processing expired subscriptions).
  • Consider adding a scheduled job to clean up stale subscriptions:

    // app/Console/Commands/CleanupExpiredSubscriptions.php
    use NotificationChannels\WebPush\Events\SubscriptionExpired;
    
    protected function handle() {
        event(new SubscriptionExpired());
        // Or use a queue job for async processing.
    }
    

• Dependency Updates:
  • Underlying web-push-php library is actively maintained (v10+). Monitor for breaking changes (e.g., encryption defaults in v11.0.0).

Support

• Common Issues:
  • Safari Errors: BadJwtToken (missing VAPID_SUBJECT), InvalidTtl (TTL too large).
  • Chrome Throttling: Notifications may be delayed or dropped if sent too frequently.
  • Payload Rejection: Large payloads (>4KB) will fail silently.
• Debugging Tools:
  • Use NotificationFailed events to log errors.
  • Test with Web Push Curl