laravel-notification-channels / aws-sns
Amazon Simple Notification Service (AWS SNS) notification channel for Laravel.
Installs: 666 468
Dependents: 1
Suggesters: 0
Security: 0
Stars: 50
Watchers: 9
Forks: 9
Open Issues: 0
Requires
- php: >=8.1
- aws/aws-sdk-php: ^3.69.11
- guzzlehttp/guzzle: ^6.2.1 || ^7.0
- illuminate/notifications: ^9.0|^10.0 || ^11.0
- illuminate/support: ^9.0|^10.0 || ^11.0
Requires (Dev)
- mockery/mockery: ^1.5.1
- phpunit/phpunit: ^9.5.10 || ^10.5
README
This package makes it easy to send notifications using AWS SNS with Laravel framework. Since Laravel already ships with SES email support, this package focuses on sending only SMS notifications for now. More advanced features like support for topics could be added in the future.
Contents
Installation
You can install the package via composer:
composer require laravel-notification-channels/aws-sns --update-with-dependencies
Setting up the AWS SNS service
Add your AWS key ID, secret and default region to your config/services.php
:
<?php return [ // ... 'sns' => [ 'key' => env('AWS_ACCESS_KEY_ID'), 'secret' => env('AWS_SECRET_ACCESS_KEY'), 'region' => env('AWS_DEFAULT_REGION', 'us-east-1'), ], ];
Usage
Now you can use the channel in your via()
method inside the notification:
<?php use NotificationChannels\AwsSns\SnsChannel; use NotificationChannels\AwsSns\SnsMessage; use Illuminate\Notifications\Notification; class AccountApproved extends Notification { public function via($notifiable) { return [SnsChannel::class]; } public function toSns($notifiable) { // You can just return a plain string: return "Your {$notifiable->service} account was approved!"; // OR explicitly return a SnsMessage object passing the message body: return new SnsMessage("Your {$notifiable->service} account was approved!"); // OR return a SnsMessage passing the arguments via `create()` or `__construct()`: return SnsMessage::create([ 'body' => "Your {$notifiable->service} account was approved!", 'transactional' => true, 'sender' => 'MyBusiness', ]); // OR create the object with or without arguments and then use the fluent API: return SnsMessage::create() ->body("Your {$notifiable->service} account was approved!") ->promotional() ->sender('MyBusiness'); } }
In order to let your Notification know which phone are you sending to, the channel
will look for the phone
, phone_number
or full_phone
attribute of the
Notifiable model. If you want to override this behaviour, add the
routeNotificationForSns
method to your Notifiable model.
<?php use Illuminate\Notifications\Notifiable; class SomeModel { use Notifiable; public function routeNotificationForSns($notification) { return '+1234567890'; } }
Available SnsMessage methods
create([])
: Accepts an array of key-values where the keys corresponds to the methods below and the values are passed as parameters;body('')
: Accepts a string value for the notification body. Messages with more than 140 characters will be split into multiple messages by SNS without breaking any words;promotional(bool)
: Sets the delivery type as promotional (default). Optimizes the delivery for lower costs;transactional(bool)
: Sets the delivery type as transactional. Optimizes the delivery to achieve the highest reliability (it also costs more);sender(string)
: Up to 11 characters with no spaces, that is displayed as the sender on the receiving device. Support varies by country;originationNumber(string)
: A numeric string that identifies an SMS message sender's phone number. Support may not be available in your country, see the AWS SNS Origination number docs.
More information about the SMS Attributes can be found on the AWS SNS Docs. It's important to know that the attributes set on the message will override the default ones configured in your AWS account.
Common Problems
Exception Handling
Exceptions are not thrown by the package in order to give other channels a chance to work properly. Instead, a Illuminate\Notifications\Events\NotificationFailed
event is dispatched. For debugging purposes you may listen to this event in the boot
method of EventServiceProvider.php
.
Event::listen(function (\Illuminate\Notifications\Events\NotificationFailed $event) { //Dump and die dd($event); //or log the event Log::error('SNS error', $event->data) });
Lack of Permissions on AWS
By default Laravel Vapor creates the role laravel-vapor-role
in AWS, which does not have permissions to send SMS via SNS. This results in SMS being sent successfully in local environments but will not be sent on a Vapor environment. Your messages might also not be sent if you are using an ID/Secret pair for a particular IAM user that can't interact with SNS.
In either case, you need to make sure the credentials you are using (either your role or user) are allowed to interact with the AWS services your application needs. On IAM (Identity and Access Management), you may attach the AWS Managed policy AmazonSNSFullAccess
or a more granular custom policy to the role/user your application is using.
Changelog
Please see CHANGELOG for more information what has changed recently.
Testing
$ composer test
Security
If you discover any security related issues, please email claudson@outlook.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.