README

This package makes it easy to send web push notifications with Laravel.

Features

• Easy integration with Laravel notifications: Seamlessly integrates with Laravel's notification system, allowing you to send web push notifications using familiar notification channels.
• Multiple browser support: Works with all major browsers that implement the Push API, including Chrome, Firefox, Edge, and Safari.
• VAPID support: Easily generate and manage VAPID keys for secure browser authentication.
• Flexible message options: Customize notifications with title, body, icon, actions, TTL, and more. Supports advanced options like vibration, badge, image, and custom data payloads.
• Subscription management: Convenient methods to save, update, and delete push subscriptions directly on your notifiable models.
• Automatic expired subscription cleanup: When sending a push message to an expired subscription, the package detects expired endpoints (using the expired flag of Minishlink\WebPush\MessageSentReport). This package will automatically delete expired subscriptions.
• Configurable and extendable: Publish and customize the package's config file to fit your application's needs.

Installation

You can install the package via Composer:

composer require laravel-notification-channels/webpush

First, add the NotificationChannels\WebPush\HasPushSubscriptions trait to your User model:

use NotificationChannels\WebPush\HasPushSubscriptions;

class User extends Model
{
    use HasPushSubscriptions;
}

Next, publish the migration with:

php artisan vendor:publish --provider="NotificationChannels\WebPush\WebPushServiceProvider" --tag="migrations"

Run the migrate command to create the necessary table:

php artisan migrate

You can also publish the config file with:

php artisan vendor:publish --provider="NotificationChannels\WebPush\WebPushServiceProvider" --tag="config"

Generate the VAPID keys (required for browser authentication) with:

php artisan webpush:vapid

This command will set VAPID_PUBLIC_KEY and VAPID_PRIVATE_KEY in your .env file. You need the VAPID_PUBLIC_KEY as applicationServerKey when using the Push API.

Note for Safari:

• If targeting Safari or iOS (especially after 2023), you must include the VAPID_SUBJECT variable in your .env file. This should be a valid URL (e.g. https://example.com) or a mailto: address (e.g. mailto:admin@example.com).
• Apple will reject requests with a BadJwtToken error if VAPID_SUBJECT is missing or invalid.
• The domain in VAPID_SUBJECT must be a valid, existing top-level domain (TLD).

These keys must be safely stored and should not change.

Usage

Now you can use the channel in your via() method inside the notification and send a generic web push notification:

use Illuminate\Notifications\Notification;
use NotificationChannels\WebPush\WebPushMessage;
use NotificationChannels\WebPush\WebPushChannel;

class AccountApproved extends Notification
{
    public function via($notifiable)
    {
        return [WebPushChannel::class];
    }

    public function toWebPush($notifiable, $notification)
    {
        return (new WebPushMessage)
            ->title('Approved!')
            ->icon('/approved-icon.png')
            ->body('Your account was approved!')
            ->action('View account', 'view_account')
            ->options(['TTL' => 1000]);
            // ->data(['id' => $notification->id])
            // ->badge()
            // ->dir()
            // ->image()
            // ->lang()
            // ->renotify()
            // ->requireInteraction()
            // ->tag()
            // ->vibrate()
    }
}

Declarative Web Push messages

Note: The specification for Declarative Web Push messages is still evolving and may change in the future. Browser support for this functionality is currently limited and may vary across platforms.

This package also supports Declarative Web Push messages, which aim to reduce the complexity of using push on the web in general and address some challenges of generic web push notifications like privacy concerns & battery life on mobile by making a client-side service worker optional while remaining fully backwards compatible:

use Illuminate\Notifications\Notification;
use NotificationChannels\WebPush\DeclarativeWebPushMessage;
use NotificationChannels\WebPush\WebPushChannel;

class AccountApproved extends Notification
{
    public function via($notifiable)
    {
        return [WebPushChannel::class];
    }

    public function toWebPush($notifiable, $notification)
    {
        return (new DeclarativeWebPushMessage)
            ->title('Approved!')
            ->icon('/approved-icon.png')
            ->body('Your account was approved!')
            ->action('View account', 'view_account', 'https://myapp.com/accounts')
            ->navigate('https://myapp.com');
            // ->data(['id' => $notification->id])
            // ->badge()
            // ->dir()
            // ->image()
            // ->lang()
            // ->mutable()
            // ->renotify()
            // ->requireInteraction()
            // ->silent()
            // ->tag()
            // ->timestamp()
            // ->vibrate()
            // ->options(['TTL' => 1000, 'contentType' => 'application/json'])
    }
}

You can find the available options here.

Save/Update Subscriptions

To save or update a subscription, use the updatePushSubscription($endpoint, $key = null, $token = null, $contentEncoding = null) method on your user:

$user = \App\User::find(1);

$user->updatePushSubscription($endpoint, $key, $token, $contentEncoding);

The $key and $token are optional and are used to encrypt your notifications. However, all major browsers require encryption when sending notifications.

When using the Push API, $key is the value of the getKey('p256dh') method, and $token is the value of the getKey('auth') method of the PushSubscription interface.

Delete Subscriptions

To delete a subscription, use the deletePushSubscription($endpoint) method on your user:

$user = \App\User::find(1);

$user->deletePushSubscription($endpoint);

Browser Compatibility

See the Push API browser compatibility.

Changelog

Please see CHANGELOG for more information about what has changed recently.

Testing

composer test

Security

If you discover any security-related issues, please email themsaid@gmail.com instead of using the issue tracker.

Contributing

Please see CONTRIBUTING for details.

Credits

• Cretu Eusebiu
• All Contributors

License

The MIT License (MIT). Please see License File for more information.