Download the PHP package bhhaskin/laravel-webpush without Composer

laravel-webpush

Web Push notification channel for Laravel. Sends VAPID-signed browser push notifications via Laravel's standard Notification system. Subscriptions are polymorphic, so any model (not just User) can be notified.

Built on minishlink/web-push.

Installation

Publish and run the migration:

Optionally publish the config:

VAPID keys

Generate a keypair once per deployment:

Add to your .env:

The public key is also served to the browser by GET /api/push-subscriptions/vapid-key.

Setup

Add the HasPushSubscriptions trait to any notifiable model:

The trait adds pushSubscriptions(), addPushSubscription(), removePushSubscription(), and routeNotificationForWebpush(). The last is what Laravel's notification system calls to resolve delivery targets.

Sending a notification

Define toWebPush() on your notification and include 'webpush' in via():

Send it exactly like any other notification:

The channel fans out to every PushSubscription attached to the notifiable.

Message builder

WebPushMessage is a fluent builder for the payload your service worker receives:

toPayload() returns the JSON object delivered to the service worker. getOptions() returns the Web Push protocol options (TTL, urgency, topic) forwarded to the push service.

HTTP endpoints

When webpush.routes.enabled is true (the default), three routes are registered:

POST body:

Configure prefix, middleware, or controller in config/webpush.php. Set routes.enabled to false and mount PushSubscriptionController yourself if you need multiple guards or different paths.

Client-side

Subscribe from the browser and post the subscription to /api/push-subscriptions:

A minimal service worker handler for the payload shape emitted by WebPushMessage::toPayload():

Expired subscription handling

When a push service returns 404 or 410 for a subscription, the channel dispatches Bhhaskin\LaravelWebpush\Events\PushSubscriptionExpired and, unless webpush.prune_expired is false, deletes the row. Listen for the event if you need to log, notify, or take other action before the row is removed.

Configuration reference

See config/webpush.php after publishing. Key options:

• vapid.subject / vapid.public_key / vapid.private_key: required
• model / table: swap the Eloquent model or table name
• routes.enabled / routes.prefix / routes.middleware / routes.controller
• options.TTL / options.urgency / options.topic: per-request defaults
• prune_expired: delete rows when push services report the subscription is gone

Testing