laravel-notification-channels / webpush
Web Push Notifications driver for Laravel.
Installs: 3 062 986
Dependents: 17
Suggesters: 0
Security: 0
Stars: 739
Watchers: 26
Forks: 125
Open Issues: 2
Requires
- php: ^8.2
- illuminate/notifications: ^11.0|^12.0
- illuminate/support: ^11.0|^12.0
- minishlink/web-push: ^9.0
Requires (Dev)
- larastan/larastan: ^3.1
- laravel/pint: ^1.21
- mockery/mockery: ^1.0
- orchestra/testbench: ^9.2|^10.0
- phpunit/phpunit: ^10.5|^11.5.3
- rector/rector: ^2.0
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 ofMinishlink\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 amailto:
address (e.g.mailto:admin@example.com
).- Apple will reject requests with a
BadJwtToken
error ifVAPID_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 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() } }
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
License
The MIT License (MIT). Please see License File for more information.