alhaji-aki / laravel-sms
A package that allows developers integrate sms providers and provide a common api to send their users messages.
Installs: 1 029
Dependents: 0
Suggesters: 0
Security: 0
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 1
Requires
- php: ^8.1|^8.2|^8.3
- illuminate/contracts: ^10.0|^11.0
- illuminate/notifications: ^10.0|^11.0
- illuminate/support: ^10.0|^11.0
- propaganistas/laravel-phone: ^5.3
Requires (Dev)
- helliomessaging/helliomessaging-laravel-notification-channel: ^1.4
- larastan/larastan: ^2.9
- laravel/pint: ^1.13
- mockery/mockery: ^1.3
- orchestra/testbench: ^8.0|^9.0
- phpunit/phpunit: ^10.5
- thecodingmachine/phpstan-safe-rule: ^1.2
- thecodingmachine/safe: ^2.5
Suggests
- helliomessaging/helliomessaging-laravel-notification-channel: Required to enable support for the Hellio sender (^1.4).
This package is auto-updated.
Last update: 2025-03-27 22:34:05 UTC
README
Laravel SMS is a package that provides a simple and flexible way to send SMS messages from your Laravel application. It supports multiple SMS providers and allows you to easily switch between them.
Installation
You can install the package via composer by running:
composer require "alhaji-aki/laravel-sms"
Configuration
After the installation has completed, the package will automatically register itself. Run the following to publish the config file
php artisan vendor:publish --provider="AlhajiAki\Sms\SmsServiceProvider"
This will create a sms.php
file in your config folder where you can configure your SMS providers and other settings. The config file looks like this
<?php return [ /* |-------------------------------------------------------------------------- | Default Sender |-------------------------------------------------------------------------- | | This option controls the default sms sender that is used to send all text | messages unless another sender is explicitly specified when sending | the message. All additional senders can be configured within the | "senders" array. Examples of each type of senders are provided. | */ 'default' => env('SMS_SENDER', 'log'), /* |-------------------------------------------------------------------------- | Global "From" Address |-------------------------------------------------------------------------- | | You may wish for all text messages sent by your application to be sent from | the same address. Here you may specify a name and address that is | used globally for all messages that are sent by your application. | */ 'from' => env('SMS_FROM_NAME', 'Example'), /* |-------------------------------------------------------------------------- | Sender Configurations |-------------------------------------------------------------------------- | | Here you may configure all of the senders used by your application plus | their respective settings. Several examples have been configured for | you and you are free to add your own as your application requires. | | This package supports a variety of sms "senders" that can be used | when delivering a text message. You may specify which one you're using for | your senders below. You may also add additional senders if needed. | | Supported: "hellio", "log", "array", "slack", "failover", "roundrobin" | */ 'senders' => [ 'hellio' => [ 'sender' => 'hellio', 'client_id' => env('HELLIO_CLIENT_ID'), 'app_secret' => env('HELLIO_APP_SECRET'), 'from' => env('HELLIO_SENDER_ID'), ], 'frog_sms' => [ 'sender' => 'frog_sms', 'username' => env('FROG_SMS_USERNAME'), 'password' => env('FROG_SMS_PASSWORD'), 'from' => env('FROG_SMS_SENDER_ID'), 'service_type' => 'SMS', 'message_type' => env('FROG_SMS_MESSAGE_TYPE', 'text'), ], 'slack' => [ 'sender' => 'slack', 'webhook_url' => env('SMS_SLACK_WEBHOOK_URL'), 'from' => env('SMS_SLACK_USERNAME'), 'emoji' => env('SMS_LOG_SLACK_EMOJI'), ], 'log' => [ 'sender' => 'log', 'channel' => env('SMS_LOG_CHANNEL'), ], 'array' => [ 'sender' => 'array', ], 'failover' => [ 'sender' => 'failover', 'senders' => [ 'log', ], ], 'roundrobin' => [ 'sender' => 'roundrobin', 'senders' => [ 'log', 'array', ], ], ], ];
The package comes preconfigured for sms providers like Hellio, Wigal, Slack, Log and array.
Failover Configuration
The failover mechanism allows you to define multiple providers to be used in case the primary provider fails. The configuration array for your application's failover sender should contain an array of senders that reference the order in which configured senders should be chosen for delivery:
'senders' => [ 'failover' => [ 'sender' => 'failover', 'senders' => [ 'log', 'slack', ], ], // ... ],
Once your failover sender has been defined, you should set this sender as the default sender used by your application by specifying its name as the value of the default
configuration key within your application's sms
configuration file:
'default' => env('SMS_SENDER', 'failover'),
Round Robin Configuration
The roundrobin
sender allows you to distribute SMS sending across multiple senders to balance the load. To get started, define a sender within your application's sms
configuration file that uses the roundrobin
sender. The configuration array for your application's roundrobin
sender should contain an array of senders
that reference which configured senders should be used for delivery:
'senders' => [ 'roundrobin' => [ 'sender' => 'roundrobin', 'senders' => [ 'log', 'array', ], ], // ... ],
Setting the FROM
This package allows you to set the from
address of your sms in two ways the global way or per sender.
Using a Global from
Address
If your application uses the same "from" address for all of its sms, it can become cumbersome to add it to each sender. Instead, you may specify a global "from" address in your config/sms.php
configuration file. This address will be used if no other "from" address is specified when sending the sms:
'from' => env('SMS_FROM_NAME', 'Example'),
Using Sender Level from
Address
If each sender has their own "from" address, you can specify it in the sender's configuration in the config/sms.php
configuration file. This address will be used if no other "from" address is specified when sending the sms:
'senders' => [ 'hellio' => [ 'sender' => 'hellio', 'client_id' => env('HELLIO_CLIENT_ID'), 'app_secret' => env('HELLIO_APP_SECRET'), 'from' => env('HELLIO_SENDER_ID'), ], // ... ],
You can also specify a from
address when sending the sms. The from
specified when sending the message takes precedence over the from
set at the Sender level in the sender's configuration. This also takes precedence over the global from
set in the config/sms.php
configuration file.
Usage
In a notification class
To use this package in your notifications, in your notifiable model, make sure to include a routeNotificationForSms()
method, which returns a phone number. Like below:
class User extends Authenticatable { use Notifiable; /** * Route notifications for the SMS channel. * * @param \Illuminate\Notifications\Notification $notification * @return string */ public function routeNotificationForSms($notification) { return $this->phone_number; } }
Then in your notification class can use the channel sms
in your via()
method:
use AlhajiAki\Sms\Notification\Messages\SmsMessage; use Illuminate\Notifications\Notification; class AccountApproved extends Notification { public function via($notifiable) { return ['sms']; } public function toSms($notifiable) { return (new SmsMessage()) ->message("Hello sms notification channel"); } }
The \AlhajiAki\Sms\Notification\Messages\SmsMessage
class provides the following method
sender()
: Use this method when you want to change the default sender set in theconfig/sms.php
file. This method accepts a string or null.from()
: Use this method to set thefrom
address of the message. This method accepts a string.data()
: The data method provides a means for sending data that might be useful to sender class at the point of sending a message. This could be used to set the message type or any relevant information needed to be able to send the sms by sender.
Using the facade
The package provides an Sms
facade which can be used to send sms like below:
use AlhajiAki\Sms\Sms; Sms::send('Hello sms facade', '+3112345678');
If you want to use a different sender to send an sms, you can do so like below:
use AlhajiAki\Sms\Sms; Sms::sender('slack')->send('Hello sms facade', '+3112345678');
The send()
method of accepts 4 parameters explained below:
$message
: The message to be sent. This is a string.$to
: The receipient(s) fo the message. This is either a string or an array.$from
: The from address. This is a string or null. If it is not provided the sender'sfrom
or the globalfrom
set in theconfig/sms.php
file will be used.$data
: The data to be sent to the sender
Sms and Local Development
When developing an application that sends sms, you probably don't want to actually send messages to live phone numbers. This package provides several ways to "disable" the actual sending of messages during local development.
Log Driver
Instead of sending your messages, the log sender driver will write all messages to your log files for inspection. Typically, this driver would only be used during local development. For more information on configuring your application per environment, check out the configuration documentation.
Slack Driver
Alternatively, you may use the slack driver to send your messages where you may view them. This approach has the benefit of allowing you to actually inspect the final message.
Using a Global to Address
Finally, you may specify a global "to" address by invoking the alwaysTo method offered by the Sms
facade. Typically, this method should be called from the boot method of one of your application's service providers:
use AlhajiAki\Sms\Sms; /** * Bootstrap any application services. */ public function boot(): void { if ($this->app->environment('local')) { Sms::alwaysTo('+3212345678'); } }
Events
We dispatch two events while sending sms messages. The SmsMessageSending
event is dispatched prior to a message being sent, while the SmsMessageSent
event is dispatched after a message has been sent. Remember, these events are dispatched when the sms is being sent, not when it is queued. You may create event listeners for these events within your application:
use AlhajiAki\Sms\Events\SmsMessageSending; // use AlhajiAki\Sms\Events\SmsMessageSent; class LogMessage { /** *Handle the given event. */ public function handle(SmsMessageSending $event): void { // ... } }
Custom Senders
You may wish to write your own senders to deliver sms via other services that this package does not support out of the box. To get started, define a class that extends the AlhajiAki\Sms\Senders\SenderInterface
class. Then, implement the send()
and __toString()
methods on your sender:
use AlhajiAki\Sms\SentMessage; use AlhajiAki\Sms\TextMessage; class TwilioSender implements SenderInterface { /** * Create a new Twilio sender instance. */ public function __construct(protected array $config) { } /** * {@inheritdoc} */ public function send(TextMessage $message): ?SentMessage { // Implement the logic to send SMS via your custom sender } /** * Get the string representation of the sender. */ public function __toString(): string { return 'twilio'; } }
Once you've defined your custom sender, you may register it via the extend
method provided by the Sms
facade. Typically, this should be done within the boot method of your application's AppServiceProvider
service provider. A $config
argument will be passed to the closure provided to the extend
method. This argument will contain the configuration array defined for the sender in the application's config/sms.php
configuration file:
use App\Sms\TwilioSender; use AlhajiAki\Sms\Sms; /** * Bootstrap any application services. */ public function boot(): void { Sms::extend('twilio', function (array $config = []) { return new TwilioSender(/* ... */); }); }
Once your custom sender has been defined and registered, you may create a sender definition within your application's config/sms.php
configuration file that utilizes the new sender:
'twilio' => [ 'sender' => 'twilio', // ... ],
TODOs
- Add SmsFake to help testing sms sending
- Write documentation for testing sms sending
- Write tests for the entire package
Testing
vendor/bin/phpunit
Contributing
Please see CONTRIBUTING for details.
License
The MIT License (MIT). Please see License File for more information.