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: "log", "array", "slack", "failover", "roundrobin"
    |
    */

    'senders' => [

        '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 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' => [
    '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'),
    ],
 
    // ...
],

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 the config/sms.php file. This method accepts a string or null.
• from(): Use this method to set the from 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's from or the global from set in the config/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.